@cuylabs/channel-slack 0.4.0 → 0.5.1

package/README.md

@@ -25,22 +25,26 @@ use:
 npm install @slack/bolt @slack/web-api @slack/types express
 ```
 
+Postgres-backed helpers lazy-load `pg` when you pass a connection string. Install
+`pg` in applications that use those helpers without injecting their own client
+or pool.
+
 ## Import Map
 
 Prefer feature-specific imports so applications only couple to the Slack
 surface they need.
 
-| Import | Use for |
-| --- | --- |
-| `@cuylabs/channel-slack/core` | Activity parsing, formatting, sessions, turn context, shared types |
-| `@cuylabs/channel-slack/policy` | Message admission, duplicate suppression, mentioned-thread state |
-| `@cuylabs/channel-slack/history` | Slack history reading, prompt shaping, supplemental-history visibility |
-| `@cuylabs/channel-slack/bolt` | Bolt app factories, auth options, Socket Mode runtime helpers, installation stores |
-| `@cuylabs/channel-slack/setup` | Required scopes/events/settings, generated manifests, setup inspection |
-| `@cuylabs/channel-slack/diagnostics` | Slack token and scope checks |
-| `@cuylabs/channel-slack/users` | User profile lookup and mention enrichment |
-| `@cuylabs/channel-slack/targets` | Human-friendly Slack channel/user target parsing and resolution |
-| `@cuylabs/channel-slack/feedback` | Feedback Block Kit and action helpers |
+| Import                               | Use for                                                                            |
+| ------------------------------------ | ---------------------------------------------------------------------------------- |
+| `@cuylabs/channel-slack/core`        | Activity parsing, formatting, sessions, turn context, shared types                 |
+| `@cuylabs/channel-slack/policy`      | Message admission, duplicate suppression, mentioned-thread state                   |
+| `@cuylabs/channel-slack/history`     | Slack history reading, prompt shaping, supplemental-history visibility             |
+| `@cuylabs/channel-slack/bolt`        | Bolt app factories, auth options, Socket Mode runtime helpers, installation stores |
+| `@cuylabs/channel-slack/setup`       | Required scopes/events/settings, generated manifests, setup inspection             |
+| `@cuylabs/channel-slack/diagnostics` | Slack token and scope checks                                                       |
+| `@cuylabs/channel-slack/users`       | User profile lookup and mention enrichment                                         |
+| `@cuylabs/channel-slack/targets`     | Human-friendly Slack channel/user target parsing and resolution                    |
+| `@cuylabs/channel-slack/feedback`    | Feedback Block Kit and action helpers                                              |
 
 The package root re-exports `core` and `policy` as a lightweight convenience.
 Use feature-specific imports for peer-backed helpers such as `bolt`,
@@ -92,6 +96,8 @@ See [Activity](docs/concepts/activity.md).
 `policy` decides which Slack messages an adapter should process. It accepts DMs
 and direct mentions by default, can allow passive channel messages by channel or
 install scope, tracks mentioned threads, and suppresses duplicate Slack events.
+Use `createPostgresSlackMessagePolicyStateStore` when duplicate suppression and
+mentioned-thread state must survive restarts or coordinate across workers.
 
 See [Message Policy](docs/concepts/message-policy.md).
 
@@ -107,7 +113,9 @@ See [Supplemental History](docs/concepts/supplemental-history.md).
 
 `bolt` contains app factories for HTTP and Socket Mode, direct auth resolution,
 OAuth installation-store types, development installation stores, and Socket Mode
-process/runtime guards. It does not register agent handlers.
+process/runtime guards. It also exposes a Postgres advisory-lock helper for
+distributed Socket Mode single-instance coordination. It does not register agent
+handlers.
 
 See [Bolt Runtime](docs/concepts/bolt-runtime.md).
 

package/dist/bolt.d.ts

@@ -262,6 +262,34 @@ interface SlackSocketModeProcessLock {
 }
 declare function acquireSlackSocketModeProcessLock({ appSlug, appToken, enabled, lockDir, logger, }: SlackSocketModeProcessLockOptions): SlackSocketModeProcessLock | undefined;
 
+interface SlackSocketModePostgresLockClient {
+    query<T = unknown>(sql: string, values?: readonly unknown[]): Promise<{
+        rows: T[];
+        rowCount?: number | null;
+    }>;
+    release?: () => void;
+}
+interface SlackSocketModePostgresLockPool {
+    connect(): Promise<SlackSocketModePostgresLockClient>;
+    end?: () => Promise<void>;
+}
+interface SlackSocketModePostgresLockOptions {
+    appSlug: string;
+    appToken?: string;
+    client?: SlackSocketModePostgresLockClient;
+    connectionString?: string;
+    enabled?: boolean;
+    logger?: Logger;
+    namespace?: string;
+    pool?: SlackSocketModePostgresLockPool;
+}
+interface SlackSocketModePostgresLock {
+    path: string;
+    close(): Promise<void>;
+    release(): Promise<void>;
+}
+declare function acquireSlackSocketModePostgresLock({ appSlug, appToken, client, connectionString, enabled, logger, namespace, pool, }: SlackSocketModePostgresLockOptions): Promise<SlackSocketModePostgresLock | undefined>;
+
 type SlackSocketModeRuntimePolicy = "single-instance" | "external-coordination";
 interface SlackSocketModeReceiverRuntimeOptions {
     autoReconnectEnabled?: boolean;
@@ -330,6 +358,7 @@ declare class JsonFileSlackInstallationStore implements SlackInstallationStore {
     private writeInstallations;
 }
 declare function createJsonFileSlackInstallationStore(filePath: string): SlackInstallationStore;
+declare function createSlackInstallationStoreAuthorize(store: SlackInstallationStore): SlackAuthorizeFn;
 declare function getSlackInstallationKey(input: SlackInstallation | SlackInstallationQuery): string;
 
-export { type CreateSlackBoltAppOptions, type CreateSlackBoltAppResult, type CreateSlackSocketBoltAppOptions, type CreateSlackSocketBoltAppResult, InMemorySlackInstallationStore, JsonFileSlackInstallationStore, type SlackAuthorizeFn, type SlackAuthorizeResult, type SlackAuthorizeSource, type SlackCustomAuthorizeAuthOptions, type SlackDirectAuthMode, type SlackDirectAuthOptions, type SlackInstallation, type SlackInstallationQuery, type SlackInstallationStore, type SlackOAuthAuthOptions, type SlackOAuthCallbackOptions, type SlackOAuthError, type SlackOAuthInstallPathOptions, type SlackSingleWorkspaceAuthOptions, type SlackSocketModeProcessLock, type SlackSocketModeProcessLockOptions, type SlackSocketModeReceiverRuntimeOptions, type SlackSocketModeRestartGuard, type SlackSocketModeRuntime, type SlackSocketModeRuntimeOptions, type SlackSocketModeRuntimePolicy, type SlackStateStore, acquireSlackSocketModeProcessLock, createInMemorySlackInstallationStore, createJsonFileSlackInstallationStore, createSlackBoltApp, createSlackSdkLogger, createSlackSocketBoltApp, createSlackSocketModeRestartGuard, createSlackSocketModeRuntime, getSlackInstallationKey, redactSlackSocketModeLogValue };
+export { type CreateSlackBoltAppOptions, type CreateSlackBoltAppResult, type CreateSlackSocketBoltAppOptions, type CreateSlackSocketBoltAppResult, InMemorySlackInstallationStore, JsonFileSlackInstallationStore, type SlackAuthorizeFn, type SlackAuthorizeResult, type SlackAuthorizeSource, type SlackCustomAuthorizeAuthOptions, type SlackDirectAuthMode, type SlackDirectAuthOptions, type SlackInstallation, type SlackInstallationQuery, type SlackInstallationStore, type SlackOAuthAuthOptions, type SlackOAuthCallbackOptions, type SlackOAuthError, type SlackOAuthInstallPathOptions, type SlackSingleWorkspaceAuthOptions, type SlackSocketModePostgresLock, type SlackSocketModePostgresLockClient, type SlackSocketModePostgresLockOptions, type SlackSocketModePostgresLockPool, type SlackSocketModeProcessLock, type SlackSocketModeProcessLockOptions, type SlackSocketModeReceiverRuntimeOptions, type SlackSocketModeRestartGuard, type SlackSocketModeRuntime, type SlackSocketModeRuntimeOptions, type SlackSocketModeRuntimePolicy, type SlackStateStore, acquireSlackSocketModePostgresLock, acquireSlackSocketModeProcessLock, createInMemorySlackInstallationStore, createJsonFileSlackInstallationStore, createSlackBoltApp, createSlackInstallationStoreAuthorize, createSlackSdkLogger, createSlackSocketBoltApp, createSlackSocketModeRestartGuard, createSlackSocketModeRuntime, getSlackInstallationKey, redactSlackSocketModeLogValue };

package/dist/bolt.js

@@ -363,6 +363,141 @@ function formatLockError(error) {
   return error instanceof Error ? error.message : String(error);
 }
 
+// src/bolt/postgres-socket-lock.ts
+import crypto2 from "crypto";
+var DEFAULT_LOCK_NAMESPACE = "channel-slack-socket";
+async function acquireSlackSocketModePostgresLock({
+  appSlug,
+  appToken,
+  client,
+  connectionString,
+  enabled = true,
+  logger,
+  namespace = DEFAULT_LOCK_NAMESPACE,
+  pool
+}) {
+  if (!enabled) {
+    logger?.debug?.("Slack Socket Mode Postgres lock skipped", {
+      reason: "disabled"
+    });
+    return void 0;
+  }
+  if (!appToken?.trim()) {
+    throw new Error(
+      "Slack app token is required when the Slack Socket Mode Postgres lock is enabled."
+    );
+  }
+  const tokenHash = hashValue(appToken);
+  const [key1, key2] = advisoryLockKeys(`${namespace}:${appSlug}:${tokenHash}`);
+  const lockPath = `postgres-advisory:${key1}:${key2}`;
+  let activePool = pool;
+  let ownsPool = false;
+  let activeClient = client;
+  let released = false;
+  try {
+    if (!activeClient) {
+      if (!activePool) {
+        if (!connectionString) {
+          throw new Error(
+            "connectionString is required when a Postgres Slack Socket Mode lock client or pool is not provided"
+          );
+        }
+        const Pool = await importPostgresPoolConstructor();
+        activePool = new Pool({ connectionString });
+        ownsPool = true;
+      }
+      activeClient = await activePool.connect();
+    }
+    const result = await activeClient.query(
+      "SELECT pg_try_advisory_lock($1::integer, $2::integer) AS acquired",
+      [key1, key2]
+    );
+    if (!result.rows[0]?.acquired) {
+      if (activeClient !== client) {
+        activeClient.release?.();
+        activeClient = void 0;
+      }
+      if (ownsPool) {
+        await activePool?.end?.();
+        activePool = void 0;
+      }
+      throw new Error(
+        `Another Slack Socket Mode process appears to hold the Postgres advisory lock (${lockPath})`
+      );
+    }
+    logger?.info?.("Slack Socket Mode Postgres lock acquired", {
+      lockPath,
+      tokenHash
+    });
+    async function release() {
+      if (released) {
+        return;
+      }
+      released = true;
+      try {
+        const releaseResult = await activeClient?.query(
+          "SELECT pg_advisory_unlock($1::integer, $2::integer) AS released",
+          [key1, key2]
+        );
+        if (releaseResult?.rows[0]?.released === false) {
+          logger?.warn?.("Slack Socket Mode Postgres lock was not held", {
+            lockPath
+          });
+        }
+        logger?.debug?.("Slack Socket Mode Postgres lock released", {
+          lockPath
+        });
+      } finally {
+        if (activeClient !== client) {
+          activeClient?.release?.();
+        }
+        if (ownsPool) {
+          await activePool?.end?.();
+        }
+      }
+    }
+    return {
+      path: lockPath,
+      close: release,
+      release
+    };
+  } catch (error) {
+    if (activeClient && activeClient !== client) {
+      activeClient.release?.();
+    }
+    if (ownsPool) {
+      await activePool?.end?.();
+    }
+    throw error;
+  }
+}
+function hashValue(value) {
+  return crypto2.createHash("sha256").update(value).digest("hex").slice(0, 16);
+}
+function advisoryLockKeys(value) {
+  const digest = crypto2.createHash("sha256").update(value).digest();
+  return [digest.readInt32BE(0), digest.readInt32BE(4)];
+}
+async function importPostgresPoolConstructor() {
+  const dynamicImport = new Function(
+    "specifier",
+    "return import(specifier)"
+  );
+  try {
+    const pg = await dynamicImport("pg");
+    return pg.Pool;
+  } catch (error) {
+    throw new Error(
+      `The "pg" package is required when using connectionString with acquireSlackSocketModePostgresLock. Install pg or pass a pool/client. ${formatImportError(
+        error
+      )}`
+    );
+  }
+}
+function formatImportError(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
 // src/bolt/socket-runtime.ts
 var DEFAULT_CLIENT_PING_TIMEOUT_MS = 3e4;
 var DEFAULT_RESTART_GUARD_MAX_WARNINGS = 3;
@@ -393,10 +528,11 @@ function createSlackSocketModeRuntime({
   runtimePolicy = "single-instance",
   serverPingTimeoutMs = DEFAULT_SERVER_PING_TIMEOUT_MS
 }) {
+  const processLockConfigured = lockEnabled && runtimePolicy === "single-instance";
   const lock = acquireSlackSocketModeProcessLock({
     appSlug,
     appToken,
-    enabled: lockEnabled && runtimePolicy === "single-instance",
+    enabled: processLockConfigured,
     ...lockDir ? { lockDir } : {},
     ...logger ? { logger } : {}
   });
@@ -410,8 +546,9 @@ function createSlackSocketModeRuntime({
   logger?.info?.("Slack Socket Mode runtime guard configured", {
     autoReconnectEnabled,
     clientPingTimeoutMs,
-    lockEnabled: Boolean(lock),
     pingPongLoggingEnabled,
+    processLockAcquired: Boolean(lock),
+    processLockConfigured,
     restartGuardEnabled,
     restartGuardMaxWarnings,
     restartGuardWindowMs,
@@ -659,6 +796,32 @@ var JsonFileSlackInstallationStore = class {
 function createJsonFileSlackInstallationStore(filePath) {
   return new JsonFileSlackInstallationStore(filePath);
 }
+function createSlackInstallationStoreAuthorize(store) {
+  return async (source) => {
+    const installation = await store.fetchInstallation({
+      teamId: source.teamId,
+      enterpriseId: source.enterpriseId,
+      userId: source.userId,
+      conversationId: source.conversationId,
+      isEnterpriseInstall: source.isEnterpriseInstall
+    });
+    const botToken = installation.bot?.token;
+    if (!botToken) {
+      throw new Error(
+        "Slack OAuth installation is missing a bot token. Reinstall the Slack app with bot scopes."
+      );
+    }
+    return {
+      botToken,
+      botId: installation.bot?.id,
+      botUserId: installation.bot?.userId,
+      teamId: installation.team?.id ?? source.teamId,
+      enterpriseId: installation.enterprise?.id ?? source.enterpriseId,
+      userId: installation.user.id,
+      userToken: installation.user.token
+    };
+  };
+}
 function getSlackInstallationKey(input) {
   if (input.isEnterpriseInstall && "enterprise" in input && input.enterprise?.id) {
     return `enterprise:${input.enterprise.id}`;
@@ -683,10 +846,12 @@ function isNodeErrorCode(error, code) {
 export {
   InMemorySlackInstallationStore,
   JsonFileSlackInstallationStore,
+  acquireSlackSocketModePostgresLock,
   acquireSlackSocketModeProcessLock,
   createInMemorySlackInstallationStore,
   createJsonFileSlackInstallationStore,
   createSlackBoltApp,
+  createSlackInstallationStoreAuthorize,
   createSlackSdkLogger,
   createSlackSocketBoltApp,
   createSlackSocketModeRestartGuard,