-
-
Notifications
You must be signed in to change notification settings - Fork 3
/
developer-documentation.hbs
109 lines (69 loc) · 5.26 KB
/
developer-documentation.hbs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
# Developer Documentation
This documentation includes the implementation details of Auto Encrypt and is intended to aid you if you’re trying to improve, debug, or get a deeper understanding of Auto Encrypt.
If you just want to use Auto Encrypt, please see the public API, as documented in the [README](readme.md).
The developer documentation is generated using [jsdoc-to-markdown](https://github.com/jsdoc2md/jsdoc-to-markdown) from the [developer-documentation.hbs](./developer-documentation.hbs) template.
The dependency diagram generation process as part of this requires [Graphviz](https://graphviz.org/download) (`dot` command) to be installed. e.g., on Ubuntu:
```sh
sudo apt install graphviz
```
To update the documentation:
```sh
npm run generate-developer-documentation
```
## Like this? Fund us!
[Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.
We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.
## Requirements
Auto Encrypt is supported on:
- __Node:__ LTS (currently 14.16.0).
- __ECMAScript:__ [ES2019](https://node.green/#ES2019)
## Overview of relationships
__Not shown (for clarity):__ third-party Node modules, the `util` namespace with helper modules – for logging, error handling, and an async `forEach` implementation – and the `typedefs` namespace with JSDoc type definitions.
Generated using [dependency cruiser](https://github.com/sverweij/dependency-cruiser).
## Tests
Main test tasks use an automatically-managed local Pebble server instance with settings optimised for performance.
### Prerequisites
1. Add `pebble` as an alias for `127.0.0.1` and `::1` in your _/etc/hosts_ file. If you’re running in a container (e.g., using DistroBox/podman on Fedora Silverblue, make sure you set this in the _etc/hosts_ file of the host system, not the container)) e.g.
```
# Loopback entries; do not change.
# For historical reasons, localhost precedes localhost.localdomain:
127.0.0.1 localhost localhost.localdomain localhost4 localhost4.localdomain4 pebble
::1 localhost localhost.localdomain localhost6 localhost6.localdomain6 pebble
```
2. __To run staging and production tests (you do not need to do this to run the Pebble tests):__ make sure that your system is reachable from your hostname (e.g., by using a service like ngrok.)
```sh
npm -s run test
```
Tests should also pass with Pebble’s default settings and with the Let’s Encrypt staging server. The full set of test tasks are:
| Name | Server | Sleep? | Nonce reject? | Debug output? |
|-------------------------------------|---------|--------|---------------|---------------|
| test | Pebble | ✘ | ✘ | ✘ |
| test-debug | Pebble | ✘ | ✘ | ✔ |
| test-pebble-sleep | Pebble | ✔ | ✘ | ✘ |
| test-pebble-sleep-debug | Pebble | ✔ | ✘ | ✔ |
| test-pebble-sleep-noncereject | Pebble | ✔ | ✔ | ✘ |
| test-pebble-sleep-noncereject-debug | Pebble | ✔ | ✔ | ✔ |
| test-staging | Staging | n/a | n/a | ✘ |
| test-staging-debug | Staging | n/a | n/a | ✔ |
## Coverage
There are several different code coverage tasks that correspond to the test tasks. Coverage task names begin with _coverage_ instead of _test_ and there are no debug versions for them.
```sh
npm -s run coverage
```
The full set of coverage tasks are:
| Name | Server | Sleep? | Nonce reject? |
|-----------------------------------------|---------|--------|---------------|
| coverage | Pebble | ✘ | ✘ |
| coverage-pebble-sleep | Pebble | ✔ | ✘ |
| coverage-pebble-sleep-noncereject | Pebble | ✔ | ✔ |
| coverage-staging | Staging | n/a | n/a |
{{>main}}
## Like this? Fund us!
[Small Technology Foundation](https://small-tech.org) is a tiny, independent not-for-profit.
We exist in part thanks to patronage by people like you. If you share [our vision](https://small-tech.org/about/#small-technology) and want to support our work, please [become a patron or donate to us](https://small-tech.org/fund-us) today and help us continue to exist.
## Copyright
© 2020-2021 [Aral Balkan](https://ar.al), [Small Technology Foundation](https://small-tech.org).
Let’s Encrypt is a trademark of the Internet Security Research Group (ISRG). All rights reserved. Node.js is a trademark of Joyent, Inc. and is used with its permission. We are not endorsed by or affiliated with Joyent or ISRG.
## License
[AGPL version 3.0 or later.](https://www.gnu.org/licenses/agpl-3.0.en.html)