Documentation Update: Secret Managers

docs/message-sourcing-subscriptions.md

@@ -17,6 +17,23 @@ Subscribing is configured on job sources that support it with a `SUBSCRIBE` envi
 | NATS       | `JOB_SOURCE__NATS__SUBSCRIBE`     |
 | RabbitMQ   | `JOB_SOURCE__RABBITMQ__SUBSCRIBE` |
 
+## Terminology: Pull vs Poll
+
+This section describes a bit of terminology confusion that I ran into when I was researching subscribe features on
+different message broker technologies.
+
+It may be tempting to think of subscribing to messages and being assigned a message by the message broker as being a
+Pull operation. After all, RabbitMQ's underlying protocol has messages being delivered to a client. The subscription
+mode in ActiveMQ and consuming in NATS involves reading from a stream that the server writes to, which could be interpreted as a Pull
+or a Push from a certain point of view. However, these systems are not Push systems.
+
+The terms Push and Pull in message brokers specifically refer to the directionality of the connection that the messages
+are sent over. The mechanics of how messages are relayed at the protocol level is irrelevant. Thus, every message source
+and acquisition method that this template supports is a Pull. A true Push system would involve a message broker actively
+connecting to consumers in order to delegate messages them.
+
+Because of this, the template uses the terms polling and subscribe to describe messaging strategies.
+
 ## Notes on Implementing Other Subscribe Patterns
 
 A subscription job source is made to leverage the consume feature of a message provider. Like with long polling, the

docs/secret-managers.md

@@ -38,17 +38,18 @@ While the other secret managers are more straightforward with their plans, Docke
 assumptions that should be documented.
 
 In general, I would encourage the use of a secret manager other than Docker Secrets. Compared to other options it lacks
-flexibility. However, it may be exactly what is needed for a small-scale environment.
+flexibility. However, it may be all that is needed for a small-scale environment and leaves the architecture open to
+be pivoted to a different implementation.
 
 Other notes:
 
-* Unlike other secret managers, a container instance's secrets cannot be rotated without restarting the
-* Secrets are assumed to be files in `/run/secrets`
+* Unlike other secret managers, a container instance's secrets cannot be rotated without restarting the container.
+* Secrets are assumed to be files in `/run/secrets`.
     * This directory can be overridden by setting a new path in `COMMON__SECRETS__DOCKER__DIRECTORY`
 * Secret keys are assumed to be roughly equal to the underlying file specified in the Docker stack configuration. If the
-  file does not meet these guidelines and because the compose file specifies another target path within the container,
-  then the secret manager has nothing with which to resolve a key to a file containing a value. After checking the exact
-  name of the key under the secret directory, the secret manager will attempt the path with a few file extensions
+  file does not meet these guidelines because the compose file specifies another target path within the container, then
+  the secret manager has no information with which to resolve a key to a file containing a value. After checking the
+  exact name of the key under the secret directory, the secret manager will attempt the path with a few file extensions
   (though realistically, only the flat key match will probably be useful).
     * For example, with no overriding directory the key `foo-password` will be searched for under the following absolute
       paths: