docs: update overview-build-and-test and regenerate reference docs

gazette · Jan 13, 2025 · 95692a2 · 95692a2
1 parent efc250e
commit 95692a2
Show file tree

Hide file tree

Showing 20 changed files with 477 additions and 335 deletions.
diff --git a/docs/_static/cmd-gazctl-attach-uuids.txt b/docs/_static/cmd-gazctl-attach-uuids.txt
@@ -42,18 +42,11 @@ Optionally compose with "jq" to un-nest the JSON objects:
 >	| jq -c '{uuid: .uuid} + .record'
 
 
-Application Options:
-      --zone=                        Availability zone within which this process is running (default: local) [$ZONE]
-
-Logging:
-      --log.level=[info|debug|warn]  Logging level (default: info) [$LOG_LEVEL]
-      --log.format=[json|text|color] Logging output format (default: text) [$LOG_FORMAT]
-
 Help Options:
-  -h, --help                         Show this help message
+  -h, --help             Show this help message
 
 [attach-uuids command options]
-          --template=                Go text/template for output (default: "{{.UUID}},{{.Line}}\n")
-          --max-length=              Maximum allowed byte-length of an input line (default: 4194304)
-          --skip-header              Omit the first line of each input file
+          --template=    Go text/template for output (default: "{{.UUID}},{{.Line}}\n")
+          --max-length=  Maximum allowed byte-length of an input line (default: 4194304)
+          --skip-header  Omit the first line of each input file
 
diff --git a/docs/_static/cmd-gazctl-journals-append.txt b/docs/_static/cmd-gazctl-journals-append.txt
@@ -53,27 +53,34 @@ cat /dev/stdout > my-fifo &	# Hold my-fifo open so gazctl doesn't read EOF.
 gazctl journals append -l my-label --framing 'lines' --mapping 'rendezvous' --input my-fifo
 
 
-Application Options:
-      --zone=                                         Availability zone within which this process is running (default: local) [$ZONE]
-
-Logging:
-      --log.level=[info|debug|warn]                   Logging level (default: info) [$LOG_LEVEL]
-      --log.format=[json|text|color]                  Logging output format (default: text) [$LOG_FORMAT]
-
 Help Options:
-  -h, --help                                          Show this help message
+  -h, --help                                              Show this help message
 
 [journals command options]
 
+    Interact with broker journals:
+          --zone=                                         Availability zone within which this process is running (default: local) [$ZONE]
+
+    Logging:
+          --log.level=[trace|debug|info|warn|error|fatal] Logging level (default: warn) [$LOG_LEVEL]
+          --log.format=[json|text|color]                  Logging output format (default: text) [$LOG_FORMAT]
+
     Broker:
-          --broker.address=                           Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
-          --broker.cache.size=                        Size of client route cache. If <= zero, no cache is used (server always proxies) (default: 0) [$BROKER_CACHE_SIZE]
-          --broker.cache.ttl=                         Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
+          --broker.address=                               Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
+          --broker.cert-file=                             Path to the client TLS certificate [$BROKER_CERT_FILE]
+          --broker.cert-key-file=                         Path to the client TLS private key [$BROKER_CERT_KEY_FILE]
+          --broker.trusted-ca-file=                       Path to the trusted CA for client verification of server certificates
+                                                          [$BROKER_TRUSTED_CA_FILE]
+          --broker.auth-keys=                             Whitespace or comma separated, base64-encoded keys. The first key is used to sign
+                                                          Authorization tokens. [$BROKER_AUTH_KEYS]
+          --broker.cache.size=                            Size of client route cache. If <= zero, no cache is used (server always proxies)
+                                                          (default: 0) [$BROKER_CACHE_SIZE]
+          --broker.cache.ttl=                             Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
 
 [append command options]
-      -l, --selector=                                 Label selector of journals to append to
-      -i, --input=                                    Input file path. Use '-' for stdin (default: -)
-      -f, --framing=[none|lines|fixed]                Framing of records in input, if any (default: none)
-      -m, --mapping=[random|modulo|rendezvous|direct] Mapping function of records to journals (default: random)
-          --base64                                    Partition keys under 'lines' framing are interpreted as base64
+      -l, --selector=                                     Label selector of journals to append to
+      -i, --input=                                        Input file path. Use '-' for stdin (default: -)
+      -f, --framing=[none|lines|fixed]                    Framing of records in input, if any (default: none)
+      -m, --mapping=[random|modulo|rendezvous|direct]     Mapping function of records to journals (default: random)
+          --base64                                        Partition keys under 'lines' framing are interpreted as base64
 
diff --git a/docs/_static/cmd-gazctl-journals-apply.txt b/docs/_static/cmd-gazctl-journals-apply.txt
@@ -35,26 +35,33 @@ gazctl supports a flag which will send changes in batches of at most
 a single Etcd transaction and it should therefore be used with caution.
 If possible, prefer to use label selectors to limit the number of changes.
 
-Application Options:
-      --zone=                        Availability zone within which this process is running (default: local) [$ZONE]
-
-Logging:
-      --log.level=[info|debug|warn]  Logging level (default: info) [$LOG_LEVEL]
-      --log.format=[json|text|color] Logging output format (default: text) [$LOG_FORMAT]
-
 Help Options:
-  -h, --help                         Show this help message
+  -h, --help                                              Show this help message
 
 [journals command options]
 
+    Interact with broker journals:
+          --zone=                                         Availability zone within which this process is running (default: local) [$ZONE]
+
+    Logging:
+          --log.level=[trace|debug|info|warn|error|fatal] Logging level (default: warn) [$LOG_LEVEL]
+          --log.format=[json|text|color]                  Logging output format (default: text) [$LOG_FORMAT]
+
     Broker:
-          --broker.address=          Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
-          --broker.cache.size=       Size of client route cache. If <= zero, no cache is used (server always proxies) (default: 0) [$BROKER_CACHE_SIZE]
-          --broker.cache.ttl=        Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
+          --broker.address=                               Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
+          --broker.cert-file=                             Path to the client TLS certificate [$BROKER_CERT_FILE]
+          --broker.cert-key-file=                         Path to the client TLS private key [$BROKER_CERT_KEY_FILE]
+          --broker.trusted-ca-file=                       Path to the trusted CA for client verification of server certificates
+                                                          [$BROKER_TRUSTED_CA_FILE]
+          --broker.auth-keys=                             Whitespace or comma separated, base64-encoded keys. The first key is used to sign
+                                                          Authorization tokens. [$BROKER_AUTH_KEYS]
+          --broker.cache.size=                            Size of client route cache. If <= zero, no cache is used (server always proxies)
+                                                          (default: 0) [$BROKER_CACHE_SIZE]
+          --broker.cache.ttl=                             Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
 
 [apply command options]
-          --specs=                   Input specifications path to apply. Use '-' for stdin (default: -)
-          --dry-run                  Perform a dry-run of the apply
-          --max-txn-size=            maximum number of specs to be processed within an apply transaction. If 0, the default, all changes are issued in a single transaction
-                                     (default: 0)
+          --specs=                                        Input specifications path to apply. Use '-' for stdin (default: -)
+          --dry-run                                       Perform a dry-run of the apply
+          --max-txn-size=                                 maximum number of specs to be processed within an apply transaction. If 0, the default,
+                                                          all changes are issued in a single transaction (default: 0)
 
diff --git a/docs/_static/cmd-gazctl-journals-edit.txt b/docs/_static/cmd-gazctl-journals-edit.txt
@@ -29,25 +29,32 @@ gazctl supports a flag which will send changes in batches of at most
 a single Etcd transaction and it should therefore be used with caution.
 If possible, prefer to use label selectors to limit the number of changes.
 
-Application Options:
-      --zone=                        Availability zone within which this process is running (default: local) [$ZONE]
-
-Logging:
-      --log.level=[info|debug|warn]  Logging level (default: info) [$LOG_LEVEL]
-      --log.format=[json|text|color] Logging output format (default: text) [$LOG_FORMAT]
-
 Help Options:
-  -h, --help                         Show this help message
+  -h, --help                                              Show this help message
 
 [journals command options]
 
+    Interact with broker journals:
+          --zone=                                         Availability zone within which this process is running (default: local) [$ZONE]
+
+    Logging:
+          --log.level=[trace|debug|info|warn|error|fatal] Logging level (default: warn) [$LOG_LEVEL]
+          --log.format=[json|text|color]                  Logging output format (default: text) [$LOG_FORMAT]
+
     Broker:
-          --broker.address=          Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
-          --broker.cache.size=       Size of client route cache. If <= zero, no cache is used (server always proxies) (default: 0) [$BROKER_CACHE_SIZE]
-          --broker.cache.ttl=        Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
+          --broker.address=                               Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
+          --broker.cert-file=                             Path to the client TLS certificate [$BROKER_CERT_FILE]
+          --broker.cert-key-file=                         Path to the client TLS private key [$BROKER_CERT_KEY_FILE]
+          --broker.trusted-ca-file=                       Path to the trusted CA for client verification of server certificates
+                                                          [$BROKER_TRUSTED_CA_FILE]
+          --broker.auth-keys=                             Whitespace or comma separated, base64-encoded keys. The first key is used to sign
+                                                          Authorization tokens. [$BROKER_AUTH_KEYS]
+          --broker.cache.size=                            Size of client route cache. If <= zero, no cache is used (server always proxies)
+                                                          (default: 0) [$BROKER_CACHE_SIZE]
+          --broker.cache.ttl=                             Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
 
 [edit command options]
-      -l, --selector=                Label Selector query to filter on
-          --max-txn-size=            maximum number of specs to be processed within an apply transaction. If 0, the default, all changes are issued in a single transaction
-                                     (default: 0)
+      -l, --selector=                                     Label Selector query to filter on
+          --max-txn-size=                                 maximum number of specs to be processed within an apply transaction. If 0, the default,
+                                                          all changes are issued in a single transaction (default: 0)
 
diff --git a/docs/_static/cmd-gazctl-journals-fragments.txt b/docs/_static/cmd-gazctl-journals-fragments.txt
@@ -51,27 +51,34 @@ gazctl journals fragments -l name=my/journal --url-ttl 1m --from $(date -d "1 ho
 gazctl journals fragments -l my-label --format json --url-ttl 1h --from $(date -d 3AM '+%s') --to $(date -d 4:05AM '+%s') --format json
 
 
-Application Options:
-      --zone=                         Availability zone within which this process is running (default: local) [$ZONE]
-
-Logging:
-      --log.level=[info|debug|warn]   Logging level (default: info) [$LOG_LEVEL]
-      --log.format=[json|text|color]  Logging output format (default: text) [$LOG_FORMAT]
-
 Help Options:
-  -h, --help                          Show this help message
+  -h, --help                                              Show this help message
 
 [journals command options]
 
+    Interact with broker journals:
+          --zone=                                         Availability zone within which this process is running (default: local) [$ZONE]
+
+    Logging:
+          --log.level=[trace|debug|info|warn|error|fatal] Logging level (default: warn) [$LOG_LEVEL]
+          --log.format=[json|text|color]                  Logging output format (default: text) [$LOG_FORMAT]
+
     Broker:
-          --broker.address=           Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
-          --broker.cache.size=        Size of client route cache. If <= zero, no cache is used (server always proxies) (default: 0) [$BROKER_CACHE_SIZE]
-          --broker.cache.ttl=         Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
+          --broker.address=                               Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
+          --broker.cert-file=                             Path to the client TLS certificate [$BROKER_CERT_FILE]
+          --broker.cert-key-file=                         Path to the client TLS private key [$BROKER_CERT_KEY_FILE]
+          --broker.trusted-ca-file=                       Path to the trusted CA for client verification of server certificates
+                                                          [$BROKER_TRUSTED_CA_FILE]
+          --broker.auth-keys=                             Whitespace or comma separated, base64-encoded keys. The first key is used to sign
+                                                          Authorization tokens. [$BROKER_AUTH_KEYS]
+          --broker.cache.size=                            Size of client route cache. If <= zero, no cache is used (server always proxies)
+                                                          (default: 0) [$BROKER_CACHE_SIZE]
+          --broker.cache.ttl=                             Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
 
 [fragments command options]
-      -l, --selector=                 Label Selector query to filter on
-      -o, --format=[table|json|proto] Output format (default: table)
-          --from=                     Restrict to fragments created at or after this time, in unix seconds since epoch
-          --to=                       Restrict to fragments created before this time, in unix seconds since epoch
-          --url-ttl=                  Provide a signed GET URL with the given TTL
+      -l, --selector=                                     Label Selector query to filter on
+      -o, --format=[table|json|proto]                     Output format (default: table)
+          --from=                                         Restrict to fragments created at or after this time, in unix seconds since epoch
+          --to=                                           Restrict to fragments created before this time, in unix seconds since epoch
+          --url-ttl=                                      Provide a signed GET URL with the given TTL (default: 0s)
 
diff --git a/docs/_static/cmd-gazctl-journals-list.txt b/docs/_static/cmd-gazctl-journals-list.txt
@@ -24,29 +24,37 @@ typically, common configuration. This hierarchy is simply sugar for and is
 exactly equivalent to the original JournalSpecs.
 
 
-Application Options:
-      --zone=                              Availability zone within which this process is running (default: local) [$ZONE]
-
-Logging:
-      --log.level=[info|debug|warn]        Logging level (default: info) [$LOG_LEVEL]
-      --log.format=[json|text|color]       Logging output format (default: text) [$LOG_FORMAT]
-
 Help Options:
-  -h, --help                               Show this help message
+  -h, --help                                              Show this help message
 
 [journals command options]
 
+    Interact with broker journals:
+          --zone=                                         Availability zone within which this process is running (default: local) [$ZONE]
+
+    Logging:
+          --log.level=[trace|debug|info|warn|error|fatal] Logging level (default: warn) [$LOG_LEVEL]
+          --log.format=[json|text|color]                  Logging output format (default: text) [$LOG_FORMAT]
+
     Broker:
-          --broker.address=                Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
-          --broker.cache.size=             Size of client route cache. If <= zero, no cache is used (server always proxies) (default: 0) [$BROKER_CACHE_SIZE]
-          --broker.cache.ttl=              Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
+          --broker.address=                               Service address endpoint (default: http://localhost:8080) [$BROKER_ADDRESS]
+          --broker.cert-file=                             Path to the client TLS certificate [$BROKER_CERT_FILE]
+          --broker.cert-key-file=                         Path to the client TLS private key [$BROKER_CERT_KEY_FILE]
+          --broker.trusted-ca-file=                       Path to the trusted CA for client verification of server certificates
+                                                          [$BROKER_TRUSTED_CA_FILE]
+          --broker.auth-keys=                             Whitespace or comma separated, base64-encoded keys. The first key is used to sign
+                                                          Authorization tokens. [$BROKER_AUTH_KEYS]
+          --broker.cache.size=                            Size of client route cache. If <= zero, no cache is used (server always proxies)
+                                                          (default: 0) [$BROKER_CACHE_SIZE]
+          --broker.cache.ttl=                             Time-to-live of route cache entries. (default: 1m) [$BROKER_CACHE_TTL]
 
 [list command options]
-      -l, --selector=                      Label Selector query to filter on
-      -o, --format=[table|yaml|json|proto] Output format (default: table)
-      -L, --label-columns=                 Labels to present as columns, eg -L label-one -L label-two
-      -p, --primary                        Show primary column
-      -r, --replicas                       Show replicas column
-          --rf                             Show replication factor column
-          --stores                         Show fragment store column
+      -l, --selector=                                     Label Selector query to filter on
+      -o, --format=[table|yaml|json|proto]                Output format (default: table)
+      -L, --label-columns=                                Labels to present as columns, eg -L label-one -L label-two
+      -p, --primary                                       Show primary column
+      -r, --replicas                                      Show replicas column
+          --rf                                            Show replication factor column
+          --stores                                        Show fragment store column
+          --watch                                         Use a long-lived watch