serverless-ircd 0.6.0 → 0.8.0

package/packages/aws-adapter/src/connection-counter.ts

@@ -0,0 +1,89 @@
+/**
+ * O(1) admission counter for the AWS `$connect` handler.
+ *
+ * Replaces the previous full-table `Scan COUNT` over `Connections` (which
+ * grew linearly with the connection count and made `$connect` latency
+ * spike into the multi-second range). The live connection count is kept in
+ * a single meta row inside the `Connections` table and updated atomically:
+ *
+ *   - `$connect` reserves a slot with {@link incrementConnectionCount}.
+ *   - `$disconnect` / the gone-connection sweeper release a slot with
+ *     {@link decrementConnectionCount} (via `cleanupConnection`).
+ *
+ * The meta row is keyed by the {@link CONNECTION_COUNT_META_ID} sentinel
+ * and deliberately carries **no** `idleSince`, so the sweeper (which only
+ * tears down rows with a stale numeric `idleSince`) skips it; stats and
+ * the sweeper filter this id out of their connection lists.
+ */
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { UpdateCommand } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Sentinel partition key for the connection-count meta row. Real APIGW
+ * connection ids are opaque alphanumeric tokens, so this `__meta:`-prefixed
+ * value never collides.
+ */
+export const CONNECTION_COUNT_META_ID = '__meta:connectionCount__';
+
+/** Attribute name holding the integer count on the meta row. */
+export const CONNECTION_COUNT_ATTR = 'count';
+
+/**
+ * Atomically reserves one connection slot: increments the counter and
+ * returns the **new** value (i.e. including this reservation). Creates the
+ * meta row on first use via `if_not_exists`.
+ *
+ * Idempotent at the DynamoDB level: a single `UpdateItem` with
+ * `ReturnValues=UPDATED_NEW` is the whole operation — no read-modify-write
+ * loop, so concurrent `$connect` invocations never lose an increment.
+ */
+export async function incrementConnectionCount(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<number> {
+  const res = await dynamo.send(
+    new UpdateCommand({
+      TableName: tableName,
+      Key: { connectionId: CONNECTION_COUNT_META_ID },
+      UpdateExpression: 'SET #c = if_not_exists(#c, :zero) + :one',
+      ExpressionAttributeNames: { '#c': CONNECTION_COUNT_ATTR },
+      ExpressionAttributeValues: { ':zero': 0, ':one': 1 },
+      ReturnValues: 'UPDATED_NEW',
+    }),
+  );
+  const updated = res.Attributes as Record<string, unknown> | undefined;
+  const count = updated?.[CONNECTION_COUNT_ATTR];
+  return typeof count === 'number' ? count : 0;
+}
+
+/**
+ * Atomically releases one connection slot: decrements the counter, floored
+ * at 0. The `attribute_exists(count) AND count > :zero` condition makes a
+ * stray decrement (e.g. a sweeper pass after a counter-reset deploy) a
+ * silent no-op instead of driving the count negative.
+ *
+ * Errors are swallowed: the counter is best-effort and self-correcting
+ * (a drifted count only tightens or loosens the admission cap slightly;
+ * it never crashes connection teardown).
+ */
+export async function decrementConnectionCount(
+  dynamo: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<void> {
+  try {
+    await dynamo.send(
+      new UpdateCommand({
+        TableName: tableName,
+        Key: { connectionId: CONNECTION_COUNT_META_ID },
+        UpdateExpression: 'SET #c = #c - :one',
+        ConditionExpression: 'attribute_exists(#c) AND #c > :zero',
+        ExpressionAttributeNames: { '#c': CONNECTION_COUNT_ATTR },
+        ExpressionAttributeValues: { ':zero': 0, ':one': 1 },
+      }),
+    );
+  } catch {
+    // ConditionalCheckFailedException (counter missing / already 0) → no-op.
+    // Any other error is also swallowed: teardown must not fail because the
+    // admission counter drifted.
+  }
+}