docs(self-hosted): reword server-flavour comments to read naturally

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: adrians5j

packages/api-event-handler-server/src/createWebinyApiHandler.ts

@@ -131,16 +131,17 @@ export function createWebinyApiHandler(config: CreateWebinyApiHandlerConfig) {
             // Attach the WebSockets upgrade handler to the running HTTP server, backed by the shared
             // (root) connection manager so request-time sends reach the live sockets.
             //
-            // Authenticate each WebSocket upgrade from its `?token` JWT so the connection is
-            // registered under the real identity — required for targeted server→client sends
-            // (SendToIdentity matches connections by identity id). AuthenticationContext lives in the
-            // PER-REQUEST stack (registered by ApiCoreFeature, not registerRootStorage), so it isn't
-            // resolvable from the root container. We build a throwaway request-scoped child container
-            // (the same way createHandler builds one per HTTP request) and resolve it there. Only the
-            // CORE stack is needed — no transports — since this is purely the token→identity step
-            // (the SAME one the HTTP stack runs via RequestIdentityLoader), and it's tenant-independent
-            // (the HTTP stack establishes identity BEFORE tenant), so it needs no request/tenant state.
-            // Connections are infrequent (one per admin session), so the per-connection child is cheap.
+            // Each upgrade is authenticated from its `?token` JWT so the connection is registered
+            // under the real identity — targeted server→client sends need this, since SendToIdentity
+            // matches connections by identity id. The catch is that AuthenticationContext lives in the
+            // per-request stack (registered by ApiCoreFeature, not registerRootStorage), so we can't
+            // resolve it from the root container. Instead we spin up a short-lived request-scoped
+            // child container, the same way createHandler does for each HTTP request, and resolve it
+            // there. We only need the core stack, not the transports, because this is just the
+            // token→identity step the HTTP stack already runs via RequestIdentityLoader — and that step
+            // doesn't depend on the tenant (the HTTP stack resolves identity before tenant), so there's
+            // no request or tenant state to set up. Connections are rare (one per admin session), so a
+            // fresh child per connection is cheap enough.
             const authenticate = async (token: string) => {
                 const child = rootContainer.createChildContainer();
                 child.registerInstance(RequestContainer, child);

packages/api-event-handler-server/src/scheduler/ScheduledActionRecoverRoute.ts

@@ -64,9 +64,10 @@ class ScheduledActionRecoverRouteImpl implements HttpRoute.Interface {
                 await schema.build(ctx);
             }
 
-            // Boot recovery runs with no identity (no request), so bypass authorization for the list —
-            // the same escape hatch ExecuteScheduledActionUseCase uses on the run route. Without this,
-            // ListScheduledActions' permission check against the anonymous identity fails "Not authorized!".
+            // At boot there's no request and no identity, so we skip authorization for the list — the
+            // same thing ExecuteScheduledActionUseCase does on the run route. Without it, the
+            // permission check in ListScheduledActions sees the anonymous identity and fails with
+            // "Not authorized!".
             const listResult = await this.container
                 .resolve(IdentityContext)
                 .withoutAuthorization(() =>

packages/api-event-handler-server/src/scheduler/schedulerServer.ts

@@ -48,8 +48,8 @@ export function registerSchedulerServer(container: Container): void {
                     headers: { "content-type": "application/json", [SCHEDULER_HEADER]: token },
                     body: JSON.stringify({ id, namespace, tenant })
                 });
-                // fetch only rejects on network errors — a 403/500 comes back as a non-ok response,
-                // so surface it explicitly (otherwise a failed run is invisible).
+                // fetch only throws on network errors; a 403 or 500 comes back as a normal non-ok
+                // response, so we check for that explicitly — otherwise a failed run would be silent.
                 if (!res.ok) {
                     const body = await res.text().catch(() => "");
                     console.error(
@@ -98,8 +98,8 @@ export async function startSchedulerServer(rootContainer: Container): Promise<vo
                 body: JSON.stringify({})
             });
             const body = await res.json().catch(() => ({}) as Record<string, unknown>);
-            // fetch only rejects on network errors — a 403/500 comes back as a non-ok response, so
-            // surface it (a silent 403 on a token mismatch was invisible before).
+            // fetch only throws on network errors; a 403 or 500 comes back as a normal non-ok
+            // response, so we check for it here (a token-mismatch 403 used to fail silently).
             if (!res.ok) {
                 console.error(`[scheduler] boot recovery failed: HTTP ${res.status}`, body);
                 return;

packages/api-websockets-server/src/connectionManager/ServerConnectionManager.ts

@@ -17,12 +17,12 @@ export class ServerConnectionManagerImpl implements WebsocketsConnectionManager.
             headers: params.headers
         });
 
-        // Persist the connection to the shared registry. This is what makes the live socket
-        // addressable: `SendToIdentity`/`ListConnections` query the registry by identity id, then
-        // resolve the in-memory socket here by connection id. Without this row the socket exists but
-        // no identity→connectionId mapping does, so targeted server→client sends reach nothing.
-        // `connectedOn` is an ISO string (the registry filters connections lexicographically against
-        // a recency cutoff), so the epoch ms `connectedAt` is converted here.
+        // Save the connection to the shared registry — this is what lets us actually reach the
+        // socket later. SendToIdentity and ListConnections look connections up in the registry by
+        // identity id and then come back here to find the in-memory socket by connection id. If we
+        // skip this, the socket is in memory but nothing maps an identity to it, so targeted
+        // server→client sends find nobody. The registry stores `connectedOn` as an ISO string (it
+        // compares connections against a recency cutoff), so we convert the epoch-ms `connectedAt`.
         await this.registry.register({
             connectionId: params.connectionId,
             identity: params.identity,

packages/api-websockets-server/src/server/WebsocketsServer.ts

@@ -152,11 +152,12 @@ class WebsocketsServer implements IWebsocketsServer {
             const host = request.headers.host || "localhost";
             const headers = toHeaders(request.headers);
 
-            // Register the connection with its real identity (decoded from the `?token` JWT). This
-            // is async — authentication + the registry write both are — but the socket handlers
-            // below are wired synchronously so no early close/message is lost during the gap. A
-            // message arriving before registration completes is simply dropped by the
-            // `getMetadata` guard (harmless; the client re-sends nothing at connect time).
+            // Register the connection under its real identity, decoded from the `?token` JWT. Both
+            // the authentication and the registry write are async, so we kick this off without
+            // awaiting it and wire the socket handlers below synchronously — that way we don't miss a
+            // close or message that arrives during the gap. If a message does arrive before
+            // registration finishes, the `getMetadata` guard below just drops it, which is fine since
+            // the client doesn't send anything meaningful right at connect time.
             void this.registerConnection({
                 connectionId,
                 socket,
@@ -199,12 +200,12 @@ class WebsocketsServer implements IWebsocketsServer {
     }
 
     /**
-     * Authenticate the upgrade (from its `?token`/`?tenant` query, set by the app-websockets client)
-     * and register the live socket in the shared connection manager under the resolved identity +
-     * tenant. Both the identity AND the registry row are load-bearing for targeted server→client
-     * sends: `SendToIdentity` looks up connections by identity id in the registry, so a connection
-     * registered anonymously (or never registered) can't be reached. Fully guarded — a failure here
-     * must never crash the server or the upgrade; the connection just stays unaddressable.
+     * Authenticates the upgrade using the `?token`/`?tenant` query the app-websockets client sends,
+     * then registers the live socket in the shared connection manager under the resolved identity and
+     * tenant. Getting both right matters for targeted server→client sends: `SendToIdentity` finds
+     * connections by identity id in the registry, so a connection that's anonymous (or never made it
+     * into the registry) can't be reached. Everything here is guarded — if something goes wrong we
+     * don't crash the server or the upgrade, the connection just ends up unaddressable.
      */
     private async registerConnection(params: {
         connectionId: string;