@abloatai/transaction 0.37.0

package/src/source/connectorProtocol.ts

@@ -0,0 +1,189 @@
+/**
+ * The wire protocol for the Data Source reverse channel — the frames that travel
+ * over the WebSocket a connector opens to Ablo.
+ *
+ * The load, list, and commit leg of a Data Source normally arrives as an inbound
+ * webhook that Ablo posts to your HTTPS endpoint. That needs a public URL, so it
+ * cannot reach a handler running on localhost or inside a private network with no
+ * inbound path. The reverse channel flips the direction: the connector dials out
+ * to Ablo over a WebSocket and serves those same requests back over the open
+ * socket. This module defines the frames exchanged on that socket.
+ *
+ * The trust model does not change. A `request` frame carries the same signature
+ * headers (`webhook-id`, `webhook-timestamp`, `webhook-signature`) and the same
+ * raw body Ablo would have posted, so the connector verifies it through
+ * `verifyAbloSourceRequest` exactly as it would a webhook. Only the transport
+ * differs.
+ *
+ * Frames are validated with Zod as they arrive, the same discipline `contract.ts`
+ * applies to change sets: a malformed frame is rejected at the boundary, and both
+ * sides infer every wire type from one schema so they cannot silently drift.
+ */
+
+import { z } from 'zod';
+
+import { environmentSchema } from '../environment.js';
+import { WS_BEARER_SUBPROTOCOL_PREFIX } from '../auth/credentialSource.js';
+
+/**
+ * The wire-protocol version. It increases on any breaking change to a frame's
+ * shape, so a connector and server on mismatched versions fail fast during
+ * `register` rather than misparsing a frame later in the stream.
+ */
+export const SOURCE_CONNECTOR_PROTOCOL_VERSION = 1;
+
+/** The WebSocket path the connector dials, appended to its configured base URL. */
+export const SOURCE_CONNECTOR_WS_PATH = '/v1/source/listen';
+
+/**
+ * The WebSocket subprotocol that identifies a reverse-channel source connector,
+ * as opposed to the SDK's sync client, which uses `ablo.sync.v1`. During the
+ * handshake the server echoes back only this value and never the subprotocol that
+ * carries the credential, keeping the API key out of proxy and load-balancer logs.
+ */
+export const WS_SOURCE_SUBPROTOCOL = 'ablo.source.v1';
+
+/**
+ * Builds the `Sec-WebSocket-Protocol` list a connector offers during the
+ * handshake: the source subprotocol followed by the bearer credential, encoded as
+ * `ablo.bearer.<apiKey>`. A WebSocket handshake cannot carry an `Authorization`
+ * header, so the API key rides as a subprotocol instead — the same mechanism the
+ * SDK's sync client uses, which the server reads back with `extractBearer`.
+ */
+export function sourceConnectorSubprotocols(apiKey: string): string[] {
+  return [WS_SOURCE_SUBPROTOCOL, `${WS_BEARER_SUBPROTOCOL_PREFIX}${apiKey}`];
+}
+
+const headerRecord = z.record(z.string(), z.string());
+
+/**
+ * The first frame the connector sends, right after the socket opens. The server
+ * has already authenticated the connection and resolved which source it serves
+ * from the API key in the handshake, so this frame only negotiates the protocol
+ * version and carries advisory metadata.
+ */
+export const registerFrameSchema = z.object({
+  type: z.literal('register'),
+  protocolVersion: z.number().int(),
+  /**
+   * An optional client identifier, such as `@abloatai/ablo@0.12.0`, recorded in
+   * the server's logs. It is advisory only and never affects a decision.
+   */
+  client: z.string().optional(),
+});
+export type RegisterFrame = z.infer<typeof registerFrameSchema>;
+
+/**
+ * The server's acknowledgement of a successful `register`. It echoes the resolved
+ * source identity so the connector can confirm and log which source it is serving.
+ */
+export const readyFrameSchema = z.object({
+  type: z.literal('ready'),
+  protocolVersion: z.number().int(),
+  sourceId: z.string().optional(),
+  organizationId: z.string().optional(),
+  environment: environmentSchema.optional(),
+});
+export type ReadyFrame = z.infer<typeof readyFrameSchema>;
+
+/**
+ * A single load, list, or commit request the server forwards to the connector.
+ * Its `headers` and `body` are byte-for-byte what the inbound webhook path would
+ * have sent, so the connector can replay them into a `Request` and let the same
+ * handler verify the signature exactly as it would for a webhook.
+ */
+export const requestFrameSchema = z.object({
+  type: z.literal('request'),
+  /** Correlation id; the matching `response` frame carries the same value. */
+  id: z.string().min(1),
+  method: z.literal('POST'),
+  /** Synthetic absolute URL used only to construct the `Request` object. */
+  url: z.string().min(1),
+  /** The signed webhook signature headers, plus `Content-Type`. */
+  headers: headerRecord,
+  /** Raw JSON request body — exactly the bytes that were signed. */
+  body: z.string(),
+});
+export type RequestFrame = z.infer<typeof requestFrameSchema>;
+
+/**
+ * The handler's response to one `request` frame, sent back by the connector. The
+ * server matches it to the pending request by `id` and treats its `status` and
+ * `body` as though an HTTP response had returned.
+ */
+export const responseFrameSchema = z.object({
+  type: z.literal('response'),
+  id: z.string().min(1),
+  status: z.number().int(),
+  headers: headerRecord.optional(),
+  /** Raw JSON response body. */
+  body: z.string(),
+});
+export type ResponseFrame = z.infer<typeof responseFrameSchema>;
+
+/**
+ * An error either side can send for a failure that is not a normal request
+ * result, such as a rejected credential, an unsupported protocol version, or a
+ * malformed frame. When `id` is set the error belongs to that pending request and
+ * fails it; without an `id` it is a connection-level error.
+ */
+export const errorFrameSchema = z.object({
+  type: z.literal('error'),
+  id: z.string().min(1).optional(),
+  code: z.string().min(1),
+  message: z.string(),
+});
+export type ErrorFrame = z.infer<typeof errorFrameSchema>;
+
+export const connectorFrameSchema = z.discriminatedUnion('type', [
+  registerFrameSchema,
+  readyFrameSchema,
+  requestFrameSchema,
+  responseFrameSchema,
+  errorFrameSchema,
+]);
+export type ConnectorFrame = z.infer<typeof connectorFrameSchema>;
+
+/** Thrown when an incoming frame fails to parse or validate. */
+export class ConnectorProtocolError extends Error {
+  readonly code = 'source_connector_protocol_error';
+  constructor(message: string) {
+    super(message);
+    this.name = 'ConnectorProtocolError';
+  }
+}
+
+/** Serialize a frame for transmission. */
+export function encodeFrame(frame: ConnectorFrame): string {
+  return JSON.stringify(frame);
+}
+
+/**
+ * Parses and validates one incoming frame. It accepts either the string or the
+ * binary payloads a WebSocket `message` event can deliver, and throws
+ * {@link ConnectorProtocolError} on any malformed or unrecognized frame so the
+ * caller can reject the connection instead of acting on bad data.
+ */
+export function decodeFrame(
+  raw: string | ArrayBuffer | Uint8Array,
+): ConnectorFrame {
+  const text = typeof raw === 'string' ? raw : decodeBinary(raw);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new ConnectorProtocolError('Frame is not valid JSON');
+  }
+  const result = connectorFrameSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new ConnectorProtocolError(
+      `Invalid connector frame: ${result.error.message}`,
+    );
+  }
+  return result.data;
+}
+
+function decodeBinary(raw: ArrayBuffer | Uint8Array): string {
+  const bytes = raw instanceof Uint8Array ? raw : new Uint8Array(raw);
+  return new TextDecoder().decode(bytes);
+}

package/src/source/contract.ts

@@ -0,0 +1,221 @@
+/**
+ * Defines the data an ORM adapter exchanges with Ablo, expressed as Zod schemas
+ * rather than plain interfaces so every value is validated where it crosses the
+ * boundary. A malformed operation or outbox row is rejected at the edge instead of
+ * failing deep inside a transaction, and each TypeScript type is inferred from the
+ * one schema that validates it.
+ *
+ * These schemas describe the adapter's own contract: the change set it commits,
+ * the outbox row it stores, and the table migrations it ships. The operation
+ * vocabulary is not restated here — `operationSchema` is projected from the
+ * core's `commitOperationSchema`, so an action or field added to the commit
+ * contract reaches a data source by construction. The assertion at the end of
+ * this file then pins the published `SourceOperation` interface to that
+ * projection, which is what keeps the interface tied to the core rather than
+ * merely tied to a second local copy of it.
+ */
+
+import { z } from 'zod';
+import { correlationIdSchema } from '../wire/commit.js';
+import {
+  commitOperationSchema,
+  commitOperationTypeSchema,
+} from '../coordination/schema.js';
+import {
+  ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH,
+  ABLO_SOURCE_ECHO_MAX_OPERATIONS,
+  ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES,
+  type SourceCommitEcho,
+  type SourceCommitEchoMarker,
+  type SourceOperation,
+} from './types.js';
+
+const jsonObject = z.record(z.string(), z.unknown());
+
+/**
+ * Served, not mirrored. The commit vocabulary is declared once in the core; a
+ * data source speaks the same five actions, so it re-exports them rather than
+ * listing them again under a second name.
+ */
+export const operationTypeSchema = commitOperationTypeSchema;
+export type OperationType = z.infer<typeof operationTypeSchema>;
+
+/**
+ * A single operation within a change set, and the runtime validator for it.
+ *
+ * The field set is projected from `commitOperationSchema` — an operation
+ * reaching a data source is a commit operation minus the two fields the core
+ * settles internally (`bypass`, `fenceToken`). The two `min(1)` overrides are
+ * deliberate and local: this is a customer-implemented boundary, so an empty
+ * model name or row id is rejected here rather than forwarded. Stating them as
+ * an extension keeps the tightening visible as a choice instead of hiding it
+ * inside a second copy of the shape.
+ */
+export const operationSchema = commitOperationSchema
+  .omit({ bypass: true, fenceToken: true })
+  .extend({
+    model: z.string().min(1),
+    id: z.string().min(1).nullish(),
+    input: jsonObject.nullish(),
+  });
+export type Operation = z.infer<typeof operationSchema>;
+
+/** The supported customer-transaction echo mechanism. */
+export const sourceCommitEchoSchema = z.object({
+  kind: z.literal('postgres-wal'),
+  payload: z
+    .string()
+    .min(1)
+    .refine(
+      (value) => new TextEncoder().encode(value).byteLength <= ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES,
+      `WAL echo payload exceeds ${ABLO_SOURCE_ECHO_MAX_PAYLOAD_BYTES} UTF-8 bytes`,
+    ),
+});
+
+export const sourceCommitEchoOperationSchema = z.strictObject({
+  model: z.string().min(1),
+  id: z.string().min(1),
+  action: z.enum(['I', 'U', 'D']),
+  transactionId: z.string().min(1).max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH),
+});
+
+export const sourceCommitEchoMarkerSchema = z
+  .strictObject({
+    version: z.literal(1),
+    correlationId: correlationIdSchema,
+    operations: z
+      .array(sourceCommitEchoOperationSchema)
+      .min(1)
+      .max(ABLO_SOURCE_ECHO_MAX_OPERATIONS)
+      .readonly(),
+  })
+  .superRefine(({ operations }, ctx) => {
+    const seen = new Set<string>();
+    for (const [index, operation] of operations.entries()) {
+      if (seen.has(operation.transactionId)) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['operations', index, 'transactionId'],
+          message: 'WAL echo operation transactionIds must be unique',
+        });
+      }
+      seen.add(operation.transactionId);
+    }
+  });
+export type SourceCommitEchoMarkerWire = z.infer<typeof sourceCommitEchoMarkerSchema>;
+
+/**
+ * The unit a mutation wrapper commits atomically. `correlationId` is derived by
+ * Ablo from the authenticated plane, participant, and public idempotency key; it
+ * is the customer-ledger identity. It is intentionally not a raw caller-authored
+ * `clientTxId` or an operation transaction id.
+ */
+export const changeSetSchema = z.object({
+  operations: z.array(operationSchema).min(1),
+  correlationId: correlationIdSchema,
+  intentHash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+  echo: sourceCommitEchoSchema.optional(),
+});
+export type ChangeSet = z.infer<typeof changeSetSchema>;
+
+/**
+ * A row in the adapter's `ablo_outbox` table. The adapter writes it in the same
+ * transaction as the underlying row change — the transactional-outbox pattern — so
+ * a change and its event commit together or not at all. The `events()` feed later
+ * reads these rows back and hands them to Ablo, and `cursor` is the monotonic
+ * ordering key Ablo round-trips to resume where it left off.
+ */
+export const outboxEventSchema = z.object({
+  /** Stable, globally-unique id — Ablo's replay-protection key. */
+  id: z.string().min(1),
+  model: z.string().min(1),
+  entityId: z.string().min(1),
+  type: operationTypeSchema,
+  data: jsonObject.nullish(),
+  organizationId: z.string().nullish(),
+  /** Legacy source transaction id. Never use this field to settle a queued commit. */
+  clientTxId: z.string().nullish(),
+  /** Scoped server-authored identity that correlates this event to a queued commit. */
+  correlationId: correlationIdSchema.nullish(),
+  /** Stable identity of this operation within the correlated source commit. */
+  transactionId: z
+    .string()
+    .min(1)
+    .max(ABLO_SOURCE_CLIENT_TX_ID_MAX_LENGTH)
+    .nullish(),
+  occurredAt: z.number().nullish(),
+  /** Monotonic ordering key (bigint as string). `events()` pages by `cursor > ?`. */
+  cursor: z.string().min(1),
+});
+export type OutboxEvent = z.infer<typeof outboxEventSchema>;
+
+/** A page of outbox events returned by `events()`. */
+export const eventsPageSchema = z.object({
+  events: z.array(outboxEventSchema),
+  nextCursor: z.string().nullable(),
+});
+export type EventsPage = z.infer<typeof eventsPageSchema>;
+
+/**
+ * A table-creation migration an adapter ships, so you never hand-write the
+ * `ablo_idempotency` and `ablo_outbox` tables yourself. An adapter returns these
+ * from its `migrations()` method.
+ */
+export const migrationSchema = z.object({
+  /** Stable name, used as the migration filename + applied-ledger key. */
+  name: z.string().min(1),
+  /** The forward SQL. */
+  up: z.string().min(1),
+});
+export type Migration = z.infer<typeof migrationSchema>;
+
+/** Describes what an adapter's backend supports, so callers check a capability rather than infer it from behavior. */
+export const adapterCapabilitiesSchema = z.object({
+  /** `commit` is atomic across all operations in the change set. */
+  transactions: z.boolean(),
+  /** A dry-run `propose` is available; when false, proposing a change happens before the adapter is called. */
+  propose: z.boolean(),
+  /** The backend can be introspected for its schema. */
+  schemaIntrospection: z.boolean(),
+  /** The adapter can atomically emit the requested Postgres WAL marker. */
+  postgresWalEcho: z.boolean().optional(),
+  /** The wrapper atomically writes and serves an endpoint transactional outbox. */
+  outboxEvents: z.boolean(),
+});
+export type AdapterCapabilities = z.infer<typeof adapterCapabilitiesSchema>;
+
+// ── Drift guard ──────────────────────────────────────────────────────────────
+// Compile-time proof that `operationSchema` stays assignment-compatible with the
+// canonical `SourceOperation` wire type. If either side changes shape, this
+// stops compiling — the schema and the interface can never silently diverge.
+type _AssertOperationMatchesWire = Operation extends SourceOperation ? true : never;
+type _AssertWireMatchesOperation = SourceOperation extends Operation ? true : never;
+const _operationContractInSync: [_AssertOperationMatchesWire, _AssertWireMatchesOperation] = [
+  true,
+  true,
+];
+void _operationContractInSync;
+
+type _AssertEchoMatchesWire = z.infer<typeof sourceCommitEchoSchema> extends SourceCommitEcho
+  ? true
+  : never;
+type _AssertWireMatchesEcho = SourceCommitEcho extends z.infer<typeof sourceCommitEchoSchema>
+  ? true
+  : never;
+const _echoContractInSync: [_AssertEchoMatchesWire, _AssertWireMatchesEcho] = [
+  true,
+  true,
+];
+void _echoContractInSync;
+
+type _AssertEchoMarkerMatchesWire = SourceCommitEchoMarkerWire extends SourceCommitEchoMarker
+  ? true
+  : never;
+type _AssertWireMatchesEchoMarker = SourceCommitEchoMarker extends SourceCommitEchoMarkerWire
+  ? true
+  : never;
+const _echoMarkerContractInSync: [
+  _AssertEchoMarkerMatchesWire,
+  _AssertWireMatchesEchoMarker,
+] = [true, true];
+void _echoMarkerContractInSync;

package/src/source/drizzle.ts

@@ -0,0 +1 @@
+export * from './adapters/drizzle.js';