@electric-ax/agents-server 0.4.18 → 0.4.20

package/src/routing/hooks.ts

@@ -1,6 +1,7 @@
 import { SpanKind, SpanStatusCode } from '@opentelemetry/api'
 import { apiError } from '../electric-agents-http.js'
 import { ElectricAgentsError } from '../entity-manager.js'
+import { ElectricProxyError } from '../utils/server-utils.js'
 import { ELECTRIC_PRINCIPAL_HEADER } from '../principal.js'
 import { ATTR, extractTraceContext, tracer } from '../tracing.js'
 import { serverLog } from '../utils/log.js'
@@ -112,6 +113,12 @@ export function errorMapper(err: unknown, req: IRequest): Response {
   if (err instanceof ElectricAgentsError) {
     return apiError(err.status, err.code, err.message, err.details)
   }
+  if (err instanceof ElectricProxyError) {
+    serverLog.warn(
+      `[agent-server] Electric proxy rejected request (${err.code}): ${req.url}`
+    )
+    return apiError(err.status, err.code, err.message)
+  }
   serverLog.error(`[agent-server] Unhandled error:`, err)
   return apiError(500, `INTERNAL_SERVER_ERROR`, `Internal server error`)
 }

package/src/routing/internal-router.ts

@@ -30,6 +30,7 @@ import { resolveDurableStreamsRoutingAdapter } from './durable-streams-routing-a
 import { electricProxyRouter } from './electric-proxy-router.js'
 import { entitiesRouter } from './entities-router.js'
 import { entityTypesRouter } from './entity-types-router.js'
+import { pgSyncRouter } from './pg-sync-router.js'
 import { getRequestSpan } from './hooks.js'
 import { observationsRouter } from './observations-router.js'
 import { runnersRouter } from './runners-router.js'
@@ -135,6 +136,7 @@ internalRouter.all(`/runners`, runnersRouter.fetch)
 internalRouter.all(`/runners/*`, runnersRouter.fetch)
 internalRouter.all(`/entities/*`, entitiesRouter.fetch)
 internalRouter.all(`/entity-types/*`, entityTypesRouter.fetch)
+internalRouter.all(`/pg-sync/*`, pgSyncRouter.fetch)
 internalRouter.all(`/observations/*`, observationsRouter.fetch)
 internalRouter.get(`/electric/*`, electricProxyRouter.fetch)
 internalRouter.all(`*`, () => status(404))

package/src/routing/pg-sync-router.ts

@@ -0,0 +1,113 @@
+/**
+ * HTTP routes for pg-sync observation source registration.
+ */
+
+import type {
+  PgSyncOptions,
+  PgSyncRequestMetadata,
+} from '@electric-ax/agents-runtime'
+import { Type, type Static } from '@sinclair/typebox'
+import { Router, json } from 'itty-router'
+import { apiError } from '../electric-agents-http.js'
+import { ErrCodeInvalidRequest } from '../electric-agents-types.js'
+import { routeBody, withSchema } from './schema.js'
+import type { JsonRouteRequest } from './schema.js'
+import type { RouterType } from 'itty-router'
+import type { TenantContext } from './context.js'
+
+const pgSyncOptionsSchema = Type.Object({
+  url: Type.Optional(Type.String()),
+  table: Type.String(),
+  columns: Type.Optional(Type.Array(Type.String())),
+  where: Type.Optional(Type.String()),
+  params: Type.Optional(
+    Type.Union([
+      Type.Array(Type.String()),
+      Type.Record(Type.String(), Type.String()),
+    ])
+  ),
+  replica: Type.Optional(
+    Type.Union([Type.Literal(`default`), Type.Literal(`full`)])
+  ),
+})
+
+const pgSyncRequestMetadataSchema = Type.Object({
+  entityUrl: Type.Optional(Type.String()),
+  entityType: Type.Optional(Type.String()),
+  streamPath: Type.Optional(Type.String()),
+  runtimeConsumerId: Type.Optional(Type.String()),
+  wakeId: Type.Optional(Type.String()),
+})
+
+const pgSyncRegisterBodySchema = Type.Object({
+  options: pgSyncOptionsSchema,
+  metadata: Type.Optional(pgSyncRequestMetadataSchema),
+})
+
+type PgSyncRegisterBody = Static<typeof pgSyncRegisterBodySchema>
+
+export type PgSyncRoutes = RouterType<
+  JsonRouteRequest,
+  [TenantContext],
+  Response | undefined
+>
+
+export const pgSyncRouter: PgSyncRoutes = Router<
+  JsonRouteRequest,
+  [TenantContext],
+  Response | undefined
+>({
+  base: `/_electric/pg-sync`,
+})
+
+pgSyncRouter.post(
+  `/register`,
+  withSchema(pgSyncRegisterBodySchema),
+  registerPgSync
+)
+
+async function registerPgSync(
+  request: JsonRouteRequest,
+  ctx: TenantContext
+): Promise<Response> {
+  const { options, metadata } = routeBody<PgSyncRegisterBody>(request)
+
+  if (options.table.trim() === ``) {
+    return apiError(
+      400,
+      ErrCodeInvalidRequest,
+      `pgSync table must be non-empty`
+    )
+  }
+
+  if (!ctx.pgSyncBridgeManager) {
+    return apiError(
+      503,
+      ErrCodeInvalidRequest,
+      `pgSync bridge manager is not configured`
+    )
+  }
+
+  try {
+    const requestMetadata: PgSyncRequestMetadata = {
+      tenantId: ctx.service,
+      principalKind: ctx.principal.kind,
+      principalId: ctx.principal.id,
+      principalKey: ctx.principal.key,
+      principalUrl: ctx.principal.url,
+      ...(metadata ?? {}),
+    }
+    const result = await ctx.pgSyncBridgeManager.register(
+      options as PgSyncOptions,
+      requestMetadata
+    )
+
+    return json(result)
+  } catch (error) {
+    return apiError(
+      500,
+      ErrCodeInvalidRequest,
+      `pgSync registration failed: ${error instanceof Error ? error.message : String(error)}`
+    )
+  }
+}

package/src/runtime.ts

@@ -14,7 +14,12 @@ import { isPermanentElectricAgentsError } from './scheduler.js'
 import { StreamClient } from './stream-client.js'
 import { DEFAULT_TENANT_ID } from './tenant.js'
 import type { DrizzleDB } from './db/index.js'
+import { PgSyncBridgeManager } from './pg-sync-bridge-manager.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
+import type {
+  PgSyncBridgeCoordinator,
+  PgSyncBridgeManagerOptions,
+} from './pg-sync-bridge-manager.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 import type {
   CronTickPayload,
@@ -40,6 +45,8 @@ export interface ElectricAgentsTenantRuntimeOptions {
   wakeRegistry: WakeRegistry
   scheduler: SchedulerClient
   entityBridgeManager: EntityBridgeCoordinator
+  pgSyncBridgeManager?: PgSyncBridgeCoordinator
+  pgSync?: PgSyncBridgeManagerOptions
   claimWriteTokens?: ClaimWriteTokenStore
   stopWakeRegistryOnShutdown?: boolean
 }
@@ -53,6 +60,7 @@ export class ElectricAgentsTenantRuntime {
   readonly wakeRegistry: WakeRegistry
   readonly scheduler: SchedulerClient
   readonly entityBridgeManager: EntityBridgeCoordinator
+  readonly pgSyncBridgeManager: PgSyncBridgeCoordinator
   readonly claimWriteTokens: ClaimWriteTokenStore
   readonly manager: EntityManager
 
@@ -92,10 +100,21 @@ export class ElectricAgentsTenantRuntime {
         ),
       stopWakeRegistryOnShutdown: options.stopWakeRegistryOnShutdown ?? false,
     })
+    this.pgSyncBridgeManager =
+      options.pgSyncBridgeManager ??
+      new PgSyncBridgeManager(
+        this.streamClient,
+        (sourceUrl, event) => this.manager.evaluateWakes(sourceUrl, event),
+        this.registry,
+        options.pgSync
+      )
   }
 
   async stop(): Promise<void> {
-    await this.manager.shutdown()
+    await Promise.all([
+      this.manager.shutdown(),
+      this.pgSyncBridgeManager.stop(),
+    ])
   }
 
   async rehydrateCronSchedules(): Promise<void> {

package/src/scheduler.ts

@@ -228,6 +228,14 @@ export function isPermanentElectricAgentsError(err: unknown): boolean {
   )
 }
 
+function cronTaskStreamPath(
+  payload: DelayedSendPayload | CronTickPayload
+): string | null {
+  return typeof (payload as { streamPath?: unknown }).streamPath === `string`
+    ? (payload as { streamPath: string }).streamPath
+    : null
+}
+
 function normalizeTask(row: ScheduledTaskRow): {
   id: number
   tenantId: string
@@ -680,6 +688,24 @@ export class Scheduler implements SchedulerClient {
         task.fireAt
       )
 
+      const streamPath = cronTaskStreamPath(task.payload)
+      const subscriberRows = streamPath
+        ? await sql<Array<{ exists: number }>>`
+            select 1 as exists
+            from wake_registrations
+            where tenant_id = ${tenantId}
+              and source_url = ${streamPath}
+            limit 1
+          `
+        : []
+
+      // Cron streams are virtual shared sources. If no wake registrations
+      // still point at this cron stream (e.g. the owning manifest schedule was
+      // deleted), stop the chain here instead of keeping a forever-global tick
+      // alive. Rehydration/getOrCreateCronStream will seed a fresh tick when a
+      // subscription is recreated.
+      if (subscriberRows.length === 0) return
+
       await sql`
         insert into scheduled_tasks (
           tenant_id,

package/src/server.ts

@@ -36,6 +36,7 @@ import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
 import type { DurableStreamsRoutingAdapter } from './routing/durable-streams-routing-adapter.js'
 import type { OssServerContext } from './routing/oss-server-router.js'
 import type { EventSourceCatalog } from './routing/context.js'
+import type { PgSyncBridgeManagerOptions } from './pg-sync-bridge-manager.js'
 import type { StartedStandaloneAgentsRuntime } from './standalone-runtime.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 import type {
@@ -72,6 +73,7 @@ export interface ElectricAgentsServerOptions {
   allowDevPrincipalFallback?: boolean
   eventSources?: EventSourceCatalog
   ensureEventSourceWakeSource?: (sourceUrl: string) => Promise<void> | void
+  pgSync?: PgSyncBridgeManagerOptions
   /**
    * Disabled by default. When set to a positive interval, periodically
    * recovers expired dispatch claims and stale outstanding wakes.
@@ -242,6 +244,7 @@ export class ElectricAgentsServer {
         streamClient: this.streamClient,
         electricUrl: this.options.electricUrl,
         electricSecret: this.options.electricSecret,
+        pgSync: this.options.pgSync,
       })
       this.electricAgentsManager = this.standaloneRuntime.manager
       this.entityBridgeManager = this.standaloneRuntime.entityBridgeManager
@@ -446,6 +449,7 @@ export class ElectricAgentsServer {
       streamClient: this.streamClient,
       runtime: this.standaloneRuntime.runtime,
       entityBridgeManager: this.entityBridgeManager,
+      pgSyncBridgeManager: this.standaloneRuntime.runtime.pgSyncBridgeManager,
       ...(this.options.eventSources
         ? { eventSources: this.options.eventSources }
         : {}),

package/src/standalone-runtime.ts

@@ -11,6 +11,10 @@ import { WakeRegistry } from './wake-registry.js'
 import type { DrizzleDB, PgClient } from './db/index.js'
 import type { EntityManager } from './entity-manager.js'
 import type { EntityBridgeCoordinator } from './entity-bridge-manager.js'
+import type {
+  PgSyncBridgeCoordinator,
+  PgSyncBridgeManagerOptions,
+} from './pg-sync-bridge-manager.js'
 import type { CronTickPayload, DelayedSendPayload } from './scheduler.js'
 import type { DurableStreamsBearerProvider } from './stream-client.js'
 
@@ -30,8 +34,11 @@ export interface StandaloneAgentsRuntimeOptions {
   startScheduler?: boolean
   startTagStreamOutboxDrainer?: boolean
   startEntityBridgeManager?: boolean
+  startPgSyncBridgeManager?: boolean
   rehydrateOnStart?: boolean
   entityBridgeManager?: EntityBridgeCoordinator
+  pgSyncBridgeManager?: PgSyncBridgeCoordinator
+  pgSync?: PgSyncBridgeManagerOptions
 }
 
 export interface StartedStandaloneAgentsRuntime {
@@ -46,6 +53,7 @@ export interface StartedStandaloneAgentsRuntime {
   manager: EntityManager
   scheduler: Scheduler
   entityBridgeManager: EntityBridgeCoordinator
+  pgSyncBridgeManager: PgSyncBridgeCoordinator
   tagStreamOutboxDrainer: TagStreamOutboxDrainer
   stop: () => Promise<void>
 }
@@ -104,6 +112,8 @@ export async function startStandaloneAgentsRuntime(
     wakeRegistry,
     scheduler,
     entityBridgeManager,
+    pgSyncBridgeManager: options.pgSyncBridgeManager,
+    pgSync: options.pgSync,
     stopWakeRegistryOnShutdown: options.wakeRegistry ? false : true,
   })
 
@@ -112,6 +122,7 @@ export async function startStandaloneAgentsRuntime(
   const startTagStreamOutboxDrainer =
     options.startTagStreamOutboxDrainer ?? true
   const startEntityBridgeManager = options.startEntityBridgeManager ?? true
+  const startPgSyncBridgeManager = options.startPgSyncBridgeManager ?? true
   const rehydrateOnStart = options.rehydrateOnStart ?? true
   let entityBridgeManagerStarted = false
   let tagStreamOutboxDrainerStarted = false
@@ -153,6 +164,10 @@ export async function startStandaloneAgentsRuntime(
       await entityBridgeManager.start()
       entityBridgeManagerStarted = true
     }
+    if (startPgSyncBridgeManager) {
+      serverLog.info(`[agent-server] starting pg-sync bridge manager...`)
+      await runtime.pgSyncBridgeManager.start?.()
+    }
     if (startTagStreamOutboxDrainer) {
       serverLog.info(`[agent-server] starting tag stream outbox drainer...`)
       tagStreamOutboxDrainer.start()
@@ -181,6 +196,7 @@ export async function startStandaloneAgentsRuntime(
     manager: runtime.manager,
     scheduler,
     entityBridgeManager,
+    pgSyncBridgeManager: runtime.pgSyncBridgeManager,
     tagStreamOutboxDrainer,
     stop,
   }

package/src/utils/server-utils.ts

@@ -90,6 +90,25 @@ export async function fileExists(filePath: string): Promise<boolean> {
   }
 }
 
+/**
+ * Raised when an Electric shape proxy request must be rejected for security
+ * reasons (an un-scoped table, or a client `where` clause that could escape the
+ * enforced per-tenant/per-principal scoping). The global `errorMapper` hook
+ * maps this to an HTTP error response. Defined here (rather than reusing
+ * `ElectricAgentsError`) to keep this module free of the heavy entity-manager
+ * import graph.
+ */
+export class ElectricProxyError extends Error {
+  constructor(
+    readonly code: `INVALID_WHERE` | `TABLE_NOT_ALLOWED`,
+    message: string,
+    readonly status: number
+  ) {
+    super(message)
+    this.name = `ElectricProxyError`
+  }
+}
+
 export function buildElectricProxyTarget(options: {
   incomingUrl: URL
   electricUrl: string
@@ -117,7 +136,29 @@ export function buildElectricProxyTarget(options: {
     target.searchParams.set(`secret`, options.electricSecret)
   }
 
-  const table = options.incomingUrl.searchParams.get(`table`)
+  // The enforced scoping `where` is AND-combined with the client's own `where`.
+  // A client clause that is not self-contained (e.g. `1=1) OR (1=1`) could
+  // break out of its parenthesised group and neutralise the scoping under SQL
+  // operator precedence, so reject anything that isn't balanced.
+  const clientWhere = options.incomingUrl.searchParams.get(`where`)
+  if (clientWhere !== null && !isSelfContainedWhereClause(clientWhere)) {
+    throw new ElectricProxyError(`INVALID_WHERE`, `Invalid where clause`, 400)
+  }
+
+  const tableParams = options.incomingUrl.searchParams.getAll(`table`)
+  if (tableParams.length !== 1) {
+    throw new ElectricProxyError(
+      `TABLE_NOT_ALLOWED`,
+      `Table is not available through the Electric proxy`,
+      403
+    )
+  }
+
+  const table = tableParams[0]
+  // Canonicalise the upstream table after validation so duplicate client query
+  // params cannot be interpreted differently by Electric or intermediaries.
+  target.searchParams.set(`table`, table)
+
   if (table === `entities`) {
     target.searchParams.set(
       `columns`,
@@ -224,11 +265,66 @@ export function buildElectricProxyTarget(options: {
         permissionBypass: options.permissionBypass,
       })
     )
+  } else {
+    // Default-deny: every shape request gets the privileged Electric secret
+    // (when configured) injected above, so only tables with explicit column +
+    // row scoping may be proxied. Any other table (or a missing `table` param)
+    // is rejected.
+    throw new ElectricProxyError(
+      `TABLE_NOT_ALLOWED`,
+      `Table is not available through the Electric proxy`,
+      403
+    )
   }
 
   return target
 }
 
+/**
+ * Returns true when a client-supplied Electric `where` clause is self-contained:
+ * its parentheses are balanced, never close below the top level, all string
+ * (`'`) and identifier (`"`) literals are terminated, and it contains no SQL
+ * comment markers. Such a clause cannot break out of the `(...)` group it is
+ * wrapped in when AND-combined with the enforced scoping predicate, nor comment
+ * out the trailing paren the proxy appends. Characters inside string/identifier
+ * literals are ignored. Comment markers are rejected unconditionally (even where
+ * harmless) as a conservative defensive measure; dollar-quoted and `E''` strings
+ * are not modeled and only ever cause fail-safe over-rejection, never a bypass.
+ */
+function isSelfContainedWhereClause(where: string): boolean {
+  let depth = 0
+  let quote: `'` | `"` | null = null
+  for (let i = 0; i < where.length; i++) {
+    const ch = where[i]
+    if (quote !== null) {
+      if (ch === quote) {
+        if (where[i + 1] === quote) {
+          i++ // doubled quote is an escaped literal quote
+        } else {
+          quote = null
+        }
+      }
+      continue
+    }
+    if (ch === `'` || ch === `"`) {
+      quote = ch
+    } else if (ch === `(`) {
+      depth++
+    } else if (ch === `)`) {
+      depth--
+      if (depth < 0) {
+        return false
+      }
+    } else if (
+      (ch === `-` && where[i + 1] === `-`) ||
+      (ch === `/` && where[i + 1] === `*`)
+    ) {
+      return false // SQL comment marker
+    }
+  }
+  return depth === 0 && quote === null
+}
+
 export function buildReadableEntitiesWhere(options: {
   tenantId: string
   principalUrl: string

package/src/wake-registry.ts

@@ -41,6 +41,8 @@ export interface WakeEvalResult {
       collection: string
       kind: `insert` | `update` | `delete`
       key: string
+      value?: unknown
+      oldValue?: unknown
       from?: string
       from_principal?: string
       from_agent?: string
@@ -737,7 +739,23 @@ export class WakeRegistry {
     }
 
     if (message.headers.operation === `delete`) {
-      this.removeCachedRegistrationByDbId(Number(message.key))
+      // Shape keys are protocol-level identifiers and are not guaranteed to be
+      // the table primary key. The wake_registrations shape uses
+      // `replica: full`, so deletes should carry the deleted row in old_value;
+      // use that row id to remove the matching in-memory registration. If the
+      // id is unavailable, reset the cache so we fail closed rather than
+      // keeping a stale wake registration alive.
+      const oldValue = (
+        message as unknown as {
+          old_value?: { id?: unknown }
+        }
+      ).old_value
+      const oldId = Number(oldValue?.id)
+      if (Number.isFinite(oldId)) {
+        this.removeCachedRegistrationByDbId(oldId)
+      } else {
+        this.resetCachedRegistrations()
+      }
       return
     }
 
@@ -937,14 +955,21 @@ export class WakeRegistry {
       return null
     }
 
+    const value = event.value as Record<string, unknown> | undefined
     const change: WakeEvalResult[`wakeMessage`][`changes`][number] = {
       collection: eventType,
       kind,
       key: (event.key as string) || ``,
     }
 
+    if (value && `value` in value) {
+      change.value = value.value
+    }
+    if (value && `oldValue` in value) {
+      change.oldValue = value.oldValue
+    }
+
     if (eventType === `inbox`) {
-      const value = event.value as Record<string, unknown> | undefined
       if (typeof value?.from === `string`) change.from = value.from
       if (typeof value?.from_principal === `string`) {
         change.from_principal = value.from_principal