From c611f3d9c2f141e3ef9e8260d005c4211f3dfbe0 Mon Sep 17 00:00:00 2001 From: Alan Deutscher Date: Fri, 4 Sep 2026 11:01:11 -0700 Subject: [PATCH 1/3] Correct Secret Manager documentaation. --- docs/secret-managers.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/secret-managers.md b/docs/secret-managers.md index edfe3883..64956899 100644 --- a/docs/secret-managers.md +++ b/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: From b985cc9182ca49e7aef99fe3fa342e0392377b62 Mon Sep 17 00:00:00 2001 From: Alan Deutscher Date: Fri, 4 Sep 2026 11:20:14 -0700 Subject: [PATCH 2/3] Add phrasing to markdown to document my confusion about the Push/Pull terms. --- docs/message-sourcing-subscriptions.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/docs/message-sourcing-subscriptions.md b/docs/message-sourcing-subscriptions.md index 59e8cc97..2f99c6f8 100644 --- a/docs/message-sourcing-subscriptions.md +++ b/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 +delegating messages to consumers. + +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 From 8cd9219fb816b754a2a74fc487ce0e76cdc9ec02 Mon Sep 17 00:00:00 2001 From: Alan Deutscher Date: Fri, 4 Sep 2026 11:23:52 -0700 Subject: [PATCH 3/3] rephrase --- docs/message-sourcing-subscriptions.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/message-sourcing-subscriptions.md b/docs/message-sourcing-subscriptions.md index 2f99c6f8..aefc9c6c 100644 --- a/docs/message-sourcing-subscriptions.md +++ b/docs/message-sourcing-subscriptions.md @@ -30,7 +30,7 @@ or a Push from a certain point of view. However, these systems are not Push syst 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 -delegating messages to consumers. +connecting to consumers in order to delegate messages them. Because of this, the template uses the terms polling and subscribe to describe messaging strategies.