create-qpq-app 0.1.6 → 0.1.8

package/template/docusaurus/docs/config/features/tenanted-web-socket-queue.md

@@ -0,0 +1,52 @@
+---
+title: defineTenantedWebSocketQueue
+description: A defineWebSocketQueue with the tenant scope resolution pre-wired as the connection scope resolver.
+---
+
+# defineTenantedWebSocketQueue
+
+A [defineWebSocketQueue](./web-socket-queue.md) with tenant scope resolution pre-wired as its `connectionScopeResolver`: a tenant id claimed in the WebSocket Authenticate handshake is membership-checked before it is stored, and a handshake with no claim stores the user's own personal scope instead of leaving the connection unscoped. It takes the same arguments as `defineWebSocketQueue` minus `connectionScopeResolver`, which it fills in for you.
+
+The deploying service must still register the resolver implementation by calling [defineTenant](./tenant.md) (with the same `owner` used everywhere else).
+
+```typescript
+import { defineTenantedWebSocketQueue, defineTenant } from 'quidproquo-features';
+
+export default [
+  ...defineTenant({
+    owner: { module: 'ca' },
+    basePath: '/tenants',
+    routeAuthSettings: { userDirectoryName: 'users' },
+  }),
+
+  defineTenantedWebSocketQueue('my-event-bus', 'api', 'example.com', {
+    userDirectoryName: 'users',
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineTenantedWebSocketQueue(
+  eventBusName: string,
+  apiName: string,
+  rootDomain: string,
+  advancedSettings?: QPQConfigAdvancedTenantedWebsocketQueueSettings,
+): QPQConfig;
+```
+
+`QPQConfigAdvancedTenantedWebsocketQueueSettings` is `QPQConfigAdvancedWebsocketQueueSettings` with `connectionScopeResolver` omitted — see [defineWebSocketQueue](./web-socket-queue.md#advancedsettings--qpqconfigadvancedwebsocketqueuesettings-optional) for the remaining options.
+
+## Parameters
+
+Same as [defineWebSocketQueue](./web-socket-queue.md#parameters): `eventBusName`, `apiName`, `rootDomain`, and `advancedSettings` (without `connectionScopeResolver`, which this always sets to `TENANT_CONNECTION_SCOPE_RESOLVER_FN`).
+
+## Returns
+
+Same as [defineWebSocketQueue](./web-socket-queue.md#returns) — a `QPQConfig` array with the connection-scope resolver already pointed at the tenant scope resolution.
+
+## Related
+
+- [defineWebSocketQueue](./web-socket-queue.md) — the underlying define this pre-configures.
+- [defineTenant](./tenant.md) — registers `TENANT_CONNECTION_SCOPE_RESOLVER_FN` (the inline function this wires in by name) plus the rest of the tenant setup.

package/template/docusaurus/docs/config/{webserver → features}/web-socket-queue.md

@@ -5,15 +5,15 @@ description: Define a managed WebSocket messaging layer — connection tracking,
 
 # defineWebSocketQueue
 
-Defines a **WebSocket queue**: a batteries-included messaging layer on top of a raw [WebSocket API](./websocket.md). Where [defineWebsocket](./websocket.md) hands you the bare `$connect`/`$disconnect`/`$default` hooks, `defineWebSocketQueue` supplies those handlers for you and wires in a built-in service that tracks live connections, authenticates clients, and exchanges typed client/server messages (ping/pong, authenticate, service request/response, state dispatch). Inbound frames are routed by message type, and outbound messages fan out to the connections registered for a user.
+Defines a **WebSocket queue**: a batteries-included messaging layer on top of a raw [WebSocket API](../webserver/websocket.md). Where [defineWebsocket](../webserver/websocket.md) hands you the bare `$connect`/`$disconnect`/`$default` hooks, `defineWebSocketQueue` supplies those handlers for you and wires in a built-in service that tracks live connections, authenticates clients, and exchanges typed client/server messages (ping/pong, authenticate, service request/response, state dispatch). Inbound frames are routed by message type, and outbound messages fan out to the connections registered for a user.
 
 - **On AWS:** this define expands into several config settings, each deploying its own infrastructure:
-  - a [WebSocket API](./websocket.md) (API Gateway v2 WebSocket API + Lambda) whose connect/disconnect/message handlers are the queue's built-in service entry points;
+  - a [WebSocket API](../webserver/websocket.md) (API Gateway v2 WebSocket API + Lambda) whose connect/disconnect/message handlers are the queue's built-in service entry points;
   - a [key-value store](../core/key-value-store.md) (DynamoDB table) named `qpq-wsq-<apiName>`, keyed by `id` with a `userId` index, that records each live connection so messages can be addressed to a user's connections;
-  - two [globals](../core/global.md) recording the associated event-bus name and user-directory name.
+  - three [globals](../core/global.md) recording the associated event-bus name, user-directory name, and connection-scope-resolver name.
 
 ```typescript
-import { defineWebSocketQueue } from 'quidproquo-webserver';
+import { defineWebSocketQueue } from 'quidproquo-features';
 
 export default [
   defineWebSocketQueue('my-event-bus', 'api', 'example.com', {
@@ -24,7 +24,7 @@ export default [
 
 ## How it relates to defineWebsocket
 
-`defineWebSocketQueue` **calls** [defineWebsocket](./websocket.md) internally — you do not need to declare one yourself. It passes its own service handlers as the `eventProcessors`:
+`defineWebSocketQueue` **calls** [defineWebsocket](../webserver/websocket.md) internally — you do not need to declare one yourself. It passes its own service handlers as the `eventProcessors`:
 
 | Route | Handler wired by the queue |
 | --- | --- |
@@ -59,7 +59,7 @@ Logical name of the WebSocket API. Drives the resource names of the deployed API
 
 ### `rootDomain` — `string` (required)
 
-The registered domain the WebSocket API is served under (passed straight through to the underlying [defineWebsocket](./websocket.md)).
+The registered domain the WebSocket API is served under (passed straight through to the underlying [defineWebsocket](../webserver/websocket.md)).
 
 ### `advancedSettings` — `QPQConfigAdvancedWebsocketQueueSettings` (optional)
 
@@ -67,22 +67,25 @@ The registered domain the WebSocket API is served under (passed straight through
 export interface QPQConfigAdvancedWebsocketQueueSettings extends QPQConfigAdvancedSettings {
   owner?: CrossModuleOwnerWithNoResourceOverride;
   userDirectoryName?: string;
+  connectionScopeResolver?: string;
 }
 ```
 
 | Property | Type | Default | Description |
 | --- | --- | --- | --- |
 | `userDirectoryName` | `string` | `''` | Name of the [user directory](../core/user-directory.md) used to authenticate clients (stored in the `qpq-wsq-kvs-name-<apiName>` global). Enables the authenticate client/server message flow. |
+| `connectionScopeResolver` | `string` | `''` | Name of a registered [inline function](../core/inline-function.md) invoked with `{ userId, requestedScope }` on **every** Authenticate message, whether or not it claims a storage scope (stored in the `qpq-wsq-scope-resolver-<apiName>` global). It returns the effective scope to store on the connection (e.g. a membership-checked tenant scope for a claim, or the user's own scope for no claim), or throws to reject the authenticate. A scope claim with no resolver configured is rejected outright, leaving the connection unauthenticated. |
 | `owner` | `CrossModuleOwnerWithNoResourceOverride` | – | Declares the queue's resources as owned by another module/service, so this service references them instead of deploying its own. Applied to both the WebSocket API and the connection store. |
 | `deprecated` | `boolean` | `false` | Inherited from `QPQConfigAdvancedSettings`; when set, the underlying WebSocket API is not deployed. |
 
 ## Returns
 
-A `QPQConfig` array containing: two globals, the connection [key-value store](../core/key-value-store.md), and the [WebSocket API](./websocket.md) with the queue's built-in handlers.
+A `QPQConfig` array containing: three globals, the connection [key-value store](../core/key-value-store.md), and the [WebSocket API](./websocket.md) with the queue's built-in handlers.
 
 ## Related
 
-- [defineWebsocket](./websocket.md) — the raw WebSocket API this define builds on and configures for you.
+- [defineWebsocket](../webserver/websocket.md) — the raw WebSocket API this define builds on and configures for you.
 - [defineStateDispatchOverWebsockets](./state-dispatch-over-websockets.md) — routes core State-domain dispatches to clients through this queue.
+- [defineTenantedWebSocketQueue](./tenanted-web-socket-queue.md) — this define with the tenant connection-scope resolver pre-wired.
 - [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) — send a raw message to a connection on the queue's API.
 - [defineEventBus](../core/event-bus.md), [defineKeyValueStore](../core/key-value-store.md), [defineUserDirectory](../core/user-directory.md) — the underlying resources it depends on.

package/template/docusaurus/docs/config/webserver/websocket.md

@@ -101,10 +101,10 @@ A `WebSocketQPQWebServerConfigSetting` config setting (`configSettingType: WebSo
 
 ## Notes
 
-- `defineWebsocket` gives you the raw connect/disconnect/message hooks. If you want a batteries-included messaging layer — connection tracking, authentication, ping/pong, and typed client/server messages — use [defineWebSocketQueue](./web-socket-queue.md), which wires those three handlers to a built-in service for you.
+- `defineWebsocket` gives you the raw connect/disconnect/message hooks. If you want a batteries-included messaging layer — connection tracking, authentication, ping/pong, and typed client/server messages — use [defineWebSocketQueue](../features/web-socket-queue.md), which wires those three handlers to a built-in service for you.
 
 ## Related
 
-- [defineWebSocketQueue](./web-socket-queue.md) — a higher-level WebSocket setup that provides `eventProcessors` for you and manages connections and messaging.
-- [defineStateDispatchOverWebsockets](./state-dispatch-over-websockets.md) — pushes core State-domain dispatches to clients over the WebSocket queue.
+- [defineWebSocketQueue](../features/web-socket-queue.md) — a higher-level WebSocket setup that provides `eventProcessors` for you and manages connections and messaging.
+- [defineStateDispatchOverWebsockets](../features/state-dispatch-over-websockets.md) — pushes core State-domain dispatches to clients over the WebSocket queue.
 - [askWebsocketSendMessage](../../actions/webserver/websocket/ask-websocket-send-message.md) — send a message to a connected client by `connectionId`.