@abloatai/transaction 0.59.2 → 0.61.0

package/src/sessions/source.ts

@@ -0,0 +1,94 @@
+/**
+ * Runtime lifecycle for a renewable session supplied to `Ablo({ session })`.
+ *
+ * A session provider mints a credential, while this boundary decides when to
+ * reuse it. Keeping that policy here prevents HTTP requests and the WebSocket
+ * bootstrap from independently minting duplicate sessions for the same actor.
+ */
+
+import type {
+  CredentialProvider,
+  CredentialProviderResult,
+} from '../auth/credentialResult.js';
+import type {
+  SessionProvider,
+  SessionProviderResult,
+  SessionSource,
+} from './contract.js';
+import { AbloValidationError } from '../errors.js';
+import {
+  createEndpointCredentialResolver,
+  isCredentialEndpoint,
+} from '../auth/credentialEndpoint.js';
+import { protectBrowserCredentialProvider } from '../auth/browserCredentialSafety.js';
+
+const SESSION_REFRESH_SKEW_MS = 30_000;
+
+function remainsUsable(session: Exclude<SessionProviderResult, null>, now: number): boolean {
+  const expiresAt = Date.parse(session.expiresAt);
+  return Number.isFinite(expiresAt) && expiresAt - now > SESSION_REFRESH_SKEW_MS;
+}
+
+/** Cache one minted session until it approaches expiry; concurrent refreshes share one mint. */
+export function cachedSessionProvider(provider: SessionProvider): CredentialProvider {
+  let current: Exclude<SessionProviderResult, null> | null = null;
+  let refreshing: Promise<SessionProviderResult> | null = null;
+
+  return async () => {
+    if (current && remainsUsable(current, Date.now())) return current;
+    refreshing ??= provider().then((next) => {
+      current = next;
+      return next;
+    }).finally(() => {
+      refreshing = null;
+    });
+    return refreshing;
+  };
+}
+
+/** The one credential input a live transport consumes. */
+export interface SessionAccess {
+  readonly renewable: boolean;
+  credential(): Promise<CredentialProviderResult>;
+}
+
+/** Normalize a static or renewable session before it reaches a transport. */
+export function createSessionAccess(
+  source: SessionSource | null | undefined,
+  credential: () => Promise<CredentialProviderResult>,
+): SessionAccess {
+  return {
+    renewable:
+      typeof source === 'function'
+      || (typeof source === 'object' && source !== null && 'endpoint' in source),
+    credential,
+  };
+}
+
+/** Resolve the public session forms into the credential shape auth consumes. */
+export function resolveSessionCredential(
+  source: SessionSource,
+  options: {
+    readonly fetch?: typeof globalThis.fetch;
+    readonly dangerouslyAllowBrowser?: boolean;
+  },
+): string | CredentialProvider {
+  if (typeof source === 'function') {
+    return protectBrowserCredentialProvider(
+      cachedSessionProvider(source),
+      options.dangerouslyAllowBrowser,
+    );
+  }
+  if (!('endpoint' in source)) return source.token;
+  if (!isCredentialEndpoint(source.endpoint)) {
+    throw new AbloValidationError(
+      '`session.endpoint` expects a URL or path such as \'/api/ablo-session\'.',
+      { code: 'invalid_options', param: 'session.endpoint' },
+    );
+  }
+  return protectBrowserCredentialProvider(createEndpointCredentialResolver(source.endpoint, {
+    fetch: options.fetch,
+    timeoutMs: source.timeoutMs,
+    allowCrossOrigin: source.allowCrossOrigin,
+  }), options.dangerouslyAllowBrowser);
+}

package/src/transport/connection/index.ts

@@ -1,4 +1,3 @@
 /** Shared connection lifecycle boundary. */
 export * from './manager.js';
-export * from './credentialLifecycle.js';
 export * from './networkProbe.js';

package/src/transport/connection/manager.ts

@@ -42,7 +42,7 @@
 
 import { probeNetwork, type ProbeResult } from './networkProbe.js';
 import type { AuthTokenGetter } from '../../auth/credentialSource.js';
-import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
+import type { CredentialRefreshOutcome } from '../../sessions/lifecycle.js';
 import { noopLogger, type Logger } from '../../logger.js';
 import {
   noopSocketObservability,

package/src/transport/http/claimWait.ts

@@ -0,0 +1,108 @@
+import { normalizeClaimConflict } from '../../claims/conflict.js';
+import type { ClaimQueuedResponse } from '../../claims/contract.js';
+import type { HttpClaimsResource } from '../../client/resources/httpResources.js';
+import {
+  emitClaimStatus,
+  type ResolvedClaimContentionOptions,
+} from '../../client/resources/modelOperations.js';
+import { AbloClaimedError } from '../../errors.js';
+
+const GRANT_POLL_FIRST_MS = 250;
+const GRANT_POLL_INTERVAL_MS = 1_000;
+const ignoreBestEffortClaimReleaseFailure = (): undefined => undefined;
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    const done = (): void => {
+      clearTimeout(timer);
+      signal?.removeEventListener('abort', done);
+      resolve();
+    };
+    const timer = setTimeout(done, ms);
+    signal?.addEventListener('abort', done, { once: true });
+  });
+}
+
+/** Wait for a queued HTTP claim while keeping its server-side slot alive. */
+export async function awaitClaimGrantOverHttp(
+  claims: HttpClaimsResource,
+  targetLabel: string,
+  queued: ClaimQueuedResponse,
+  options: ResolvedClaimContentionOptions,
+): Promise<{ id: string; fenceToken?: number }> {
+  const claimId = queued.id;
+  const { signal } = options;
+  const conflict = normalizeClaimConflict({
+    ...(queued.heldBy !== undefined ? { heldBy: queued.heldBy } : {}),
+    ...(queued.heldByKind !== undefined ? { heldByKind: queued.heldByKind } : {}),
+    ...(queued.heldByClaimId !== undefined ? { heldByClaimId: queued.heldByClaimId } : {}),
+    ...(queued.expiresAt !== undefined ? { heldByExpiresAt: queued.expiresAt } : {}),
+    ...(queued.heldByClaim !== undefined ? { heldByClaim: queued.heldByClaim } : {}),
+  });
+  const waitingError = (
+    message: string,
+    code: 'queue_too_deep' | 'claim_wait_aborted' | 'grant_timeout' | 'claim_lost',
+  ): AbloClaimedError => new AbloClaimedError(message, {
+    code,
+    claims: queued.heldByClaim ? [queued.heldByClaim] : undefined,
+    conflict,
+  });
+  const rejectAndLeave = async (error: AbloClaimedError): Promise<never> => {
+    await claims.release({ claimId }).catch(ignoreBestEffortClaimReleaseFailure);
+    throw error;
+  };
+
+  emitClaimStatus(options.onStatus, {
+    type: 'queued',
+    claimId,
+    position: queued.position,
+    ahead: queued.position + 1,
+  });
+  if (options.maxDepth !== undefined && queued.position >= options.maxDepth) {
+    return rejectAndLeave(waitingError(
+      `Claim queue for ${targetLabel} is ${queued.position} deep (max ${options.maxDepth}).`,
+      'queue_too_deep',
+    ));
+  }
+
+  const deadline = options.timeoutMs !== undefined ? Date.now() + options.timeoutMs : undefined;
+  let delay = GRANT_POLL_FIRST_MS;
+  for (;;) {
+    if (signal?.aborted) {
+      return rejectAndLeave(waitingError(
+        `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
+        'claim_wait_aborted',
+      ));
+    }
+    if (deadline !== undefined && Date.now() >= deadline) {
+      return rejectAndLeave(waitingError(
+        `Timed out after ${options.timeoutMs}ms waiting for the queue grant on ${targetLabel}.`,
+        'grant_timeout',
+      ));
+    }
+    await sleep(
+      deadline !== undefined ? Math.min(delay, Math.max(0, deadline - Date.now())) : delay,
+      signal,
+    );
+    if (signal?.aborted) {
+      return rejectAndLeave(waitingError(
+        `The wait for the claim on ${targetLabel} was aborted before the grant arrived.`,
+        'claim_wait_aborted',
+      ));
+    }
+    delay = GRANT_POLL_INTERVAL_MS * (0.85 + Math.random() * 0.3);
+    const beat = await claims.heartbeat({ claimId });
+    if (beat.status !== 'held') continue;
+    const state = await claims.retrieve({ claimId });
+    if (state.status !== 'active') {
+      return rejectAndLeave(waitingError(
+        `Claim lost while queued for ${targetLabel}.`,
+        'claim_lost',
+      ));
+    }
+    emitClaimStatus(options.onStatus, { type: 'granted', claimId, waited: true });
+    return state.fenceToken !== undefined
+      ? { id: claimId, fenceToken: state.fenceToken }
+      : { id: claimId };
+  }
+}

package/src/transport/http/client.ts

@@ -19,9 +19,8 @@
  */
 import {
   createHttpTransport,
-  type HttpTransport,
 } from './transport.js';
-import { modelWireNames } from '../../auth/capability.js';
+import type { HttpTransport } from './contract.js';
 import type { HttpClientConfig } from './options.js';
 import type {
   CommitResource,
@@ -33,9 +32,6 @@ import type {
   ModelReadOptions,
   ModelMutationOptions,
   ModelList,
-  CreateSessionParams,
-  AbloSession,
-  SessionResource,
 } from '../../client/resources/httpResources.js';
 import { collectModelList, modelList } from '../../client/resources/httpResources.js';
 import { resolveCreateId } from '../../client/resources/modelCreate.js';
@@ -91,8 +87,8 @@ export interface AbloHttpClientOptions<S extends SchemaRecord>
    * @default 30_000
    */
   readonly timeoutMs?: number;
-  /** Initial area of interest for `transport: 'websocket'`. */
-  readonly syncGroups?: readonly string[];
+  /** Initial groups observed by a session-backed WebSocket client. */
+  readonly groups?: readonly string[];
   /** Application frame names accepted by `subscribe` on the WebSocket transport. */
   readonly collaborationEvents?: readonly string[];
   /** Durable resume position for WebSocket observation. */
@@ -123,7 +119,7 @@ export type HttpModelMutationParams<P> = Omit<P, 'reads'> & {
  * coordinated writes.
  * It deliberately omits the stateful client's local-only
  * reads (the `local` namespace) and live subscriptions (`onChange`), which need
- * a resident graph and a persistent socket; those are absent from the type, so
+ * a local graph and a persistent socket; those are absent from the type, so
  * reaching for one is a compile error rather than a runtime gap.
  *
  * This is also the base the reactive per-model surface is composed from, rather
@@ -199,7 +195,7 @@ export interface HttpModelClient<T, C = T> {
 
 /**
  * The type of the stateless HTTP client: a typed {@link HttpModelClient} per
- * schema model, plus `commits`, `dispose`, and the session-mint surface. It
+ * schema model, plus `commits` and lifecycle operations. It
  * exposes only what request/response transport can do, so reaching for a
  * stateful-only capability — the `local` reads, `onChange`, or the synchronous
  * `claim.state`/`queue`/`reorder` reads — is a compile error rather than a value
@@ -235,13 +231,6 @@ export type AbloHttpClient<S extends SchemaRecord> = {
   dispose(): Promise<void>;
   /** Resolves the bearer credential this client authenticates with, or `null` if none is set. */
   getAuthToken(): Promise<string | null>;
-  /**
-   * Mints a short-lived, scoped session token. Minting is itself a stateless
-   * request, so it is available here even though the local-cache reads are not.
-   * Pass `{ user }` to mint an end-user key (`ek_`) or `{ agent, can }` to mint a
-   * scoped agent key (`rk_`). See {@link CreateSessionParams}.
-  */
-  readonly sessions: SessionResource<S>;
 };
 
 /** The same typed resource client, with server-pushed capabilities carried by WebSocket. */
@@ -252,9 +241,9 @@ export type AbloWebSocketClient<S extends SchemaRecord> = AbloHttpClient<S> & {
     listener: (...args: CoreSyncEventMap[K]) => void,
   ): () => void;
   updateSubscription(
-    syncGroups: readonly string[],
+    groups: readonly string[],
     options?: { timeoutMs?: number },
-  ): Promise<{ syncGroups: string[] }>;
+  ): Promise<{ groups: string[] }>;
   readonly presence: {
     update(input?: {
       readonly status?: 'online' | 'away' | 'offline';
@@ -281,9 +270,10 @@ const PROTOCOL_MEMBERS = new Set<string>([
   'logs',
   'identity',
   'getAuthToken',
-  'sessions',
 ]);
 
+const ignoreAlreadySurfacedSessionOpeningFailure = (): undefined => undefined;
+
 /** Narrows a bare property name to a transport key so the facade can index it typed. */
 function isProtocolMember(prop: string): prop is keyof HttpTransport {
   return PROTOCOL_MEMBERS.has(prop);
@@ -538,23 +528,20 @@ function createHttpModelClient<T, C = T>(
 }
 
 /**
- * Builds the stateless, typed HTTP client. Each `client.<model>` resolves to the
- * protocol client's model accessor, while `commits`, `dispose`, and the other
- * protocol members pass through unchanged. No socket is ever opened; the bearer
- * credential is the identity.
+ * Builds the typed headless client. An API-key identity uses HTTP. A session
+ * identity uses one lazily opened WebSocket by default for commits and live
+ * coordination until `dispose()`; point reads and administration remain HTTP.
  */
-/** @internal Constructed only through the public `Ablo({ transport: 'http' })` factory. */
+/** @internal Constructed only through the public `Ablo()` factory. */
 export function createAbloHttpClient<S extends SchemaRecord>(
   options: AbloHttpClientOptions<S>,
 ): AbloHttpClient<S> | AbloWebSocketClient<S> {
   const { schema, onCommitReceipt, ...rest } = options;
-  const usesWebSocket = options.transport === 'websocket';
+  const usesWebSocket = options.transport === 'websocket'
+    || (options.transport === undefined && options.session != null);
   const readSetContext = createReadSetContext();
   const transport: HttpTransport = createHttpTransport({
     ...rest,
-    // Derived from the schema this client is bound to, never assembled by hand
-    // — see `auth/capability.ts`.
-    modelTypenames: modelWireNames(schema.models),
     onCommitReceipt: (observation) => {
       recordHttpCommitReceipt(readSetContext, observation);
       onCommitReceipt?.(observation);
@@ -570,9 +557,8 @@ export function createAbloHttpClient<S extends SchemaRecord>(
         return receipt;
       },
       dispatchClaim: async (input) => (await webSocketSession()).claim(input),
-      releaseDispatchedClaim: (input) => {
-        void webSocketSession().then((session) => session.release(input));
-      },
+      releaseDispatchedClaim: async (input) =>
+        (await webSocketSession()).release(input),
     } : {}),
   });
   const schemaModels = new Set(Object.keys(schema.models));
@@ -597,8 +583,8 @@ export function createAbloHttpClient<S extends SchemaRecord>(
       await transport.ready();
       const session = await createWebSocketSession({
         baseUrl: rest.baseURL ?? undefined,
-        getAuthToken: async () => (await transport.getAuthToken()) ?? undefined,
-        syncGroups: options.syncGroups,
+        access: transport.access,
+        syncGroups: options.groups,
         collaborationEvents: options.collaborationEvents,
         cursorStore: options.cursorStore,
         cursorKey: options.cursorKey,
@@ -629,7 +615,7 @@ export function createAbloHttpClient<S extends SchemaRecord>(
     webSocketOpen.abort();
     const opening = webSocketPromise;
     if (webSocket) await webSocket.close();
-    else await opening?.then((session) => session.close()).catch(() => undefined);
+    else await opening?.then((session) => session.close()).catch(ignoreAlreadySurfacedSessionOpeningFailure);
     await transport.dispose();
   };
 
@@ -707,8 +693,13 @@ export function createAbloHttpClient<S extends SchemaRecord>(
         };
       }
       if (usesWebSocket && prop === 'updateSubscription') {
-        return async (groups: readonly string[], subscriptionOptions?: { timeoutMs?: number }) =>
-          (await webSocketSession()).updateSubscription(groups, subscriptionOptions);
+        return async (groups: readonly string[], subscriptionOptions?: { timeoutMs?: number }) => {
+          const result = await (await webSocketSession()).updateSubscription(
+            groups,
+            subscriptionOptions,
+          );
+          return { groups: result.syncGroups };
+        };
       }
       if (usesWebSocket && prop === 'presence') {
         return {

package/src/transport/http/contract.ts

@@ -0,0 +1,71 @@
+/** Private contract owned by the stateless HTTP transport boundary. */
+
+import type { HttpClientConfig } from './options.js';
+import type { CommitReceiptWire } from '../../commit/contract.js';
+import type {
+  CommitResource,
+  HttpClaimsResource,
+  HttpLogsResource,
+  HttpTransportModel,
+} from '../../client/resources/httpResources.js';
+import type {
+  ClaimAcquired,
+  ClaimBeginPayload,
+  ClaimGranted,
+  ClaimQueued,
+} from '../../coordination/schema.js';
+import type { CoordinationObservability } from '../../observability.js';
+import type { EffectiveAuthority } from '../../auth/capability.js';
+import type { SessionAccess } from '../../sessions/index.js';
+import type { CommitFrameOperation } from '../websocket/commitFrames.js';
+import type { HttpReadOnChange } from './subscription.js';
+
+/** @internal Private options for the schema-agnostic HTTP protocol transport. */
+export type HttpTransportOptions = Omit<HttpClientConfig, 'schema'> & {
+  readonly bootstrapBaseUrl?: string | undefined;
+  /** Observability forwarded from `Ablo({ observability })`. */
+  readonly observability?: CoordinationObservability;
+  /** Per-request deadline in milliseconds. Pass `0` to disable it. */
+  readonly timeoutMs?: number;
+  /** @internal Routes writes through the selected duplex transport. */
+  readonly dispatchCommit?: ((input: {
+    readonly clientTxId: string;
+    readonly operations: readonly CommitFrameOperation[];
+    readonly reads?: readonly import('../../coordination/schema.js').ReadDependency[] | null;
+  }) => Promise<CommitReceiptWire>) | undefined;
+  /** @internal Routes held-claim acquisition through the shared socket. */
+  readonly dispatchClaim?: ((input: ClaimBeginPayload & {
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+    readonly onQueued?: (event: ClaimQueued) => Error | undefined;
+  }) => Promise<ClaimAcquired | ClaimGranted>) | undefined;
+  /** @internal Releases a socket-acquired claim on that same session. */
+  readonly releaseDispatchedClaim?: ((input: {
+    readonly claimId: string;
+    readonly entityType: string;
+    readonly entityId: string;
+  }) => Promise<void>) | undefined;
+};
+
+/** @internal Private protocol surface wrapped by `AbloHttpClient`. */
+export interface HttpTransport {
+  ready(): Promise<void>;
+  waitForFlush(): Promise<void>;
+  /** Drains scheduled commits and active requests. */
+  dispose(): Promise<void>;
+  purge(): Promise<void>;
+  /** @internal Live check used only by `context().onChange`. */
+  readonly onChange: HttpReadOnChange;
+  readonly commits: CommitResource;
+  readonly claims: HttpClaimsResource;
+  readonly logs: HttpLogsResource;
+  /** Server-confirmed authority of the active bearer, populated by `ready()`. */
+  readonly identity: EffectiveAuthority | null;
+  model<T = Record<string, unknown>, Fields = T>(
+    name: string,
+  ): HttpTransportModel<T, Fields>;
+  /** Resolve the bearer credential used by this transport. */
+  getAuthToken(): Promise<string | null>;
+  /** @internal One normalized source shared by HTTP bootstrap and live transport. */
+  readonly access: SessionAccess;
+}

package/src/transport/http/index.ts

@@ -1,5 +1,6 @@
 /** Stateless HTTP transport boundary. */
 export * from './options.js';
+export * from './contract.js';
 export * from './client.js';
 export * from './transport.js';
 export * from './helpers.js';

package/src/transport/http/options.ts

@@ -37,7 +37,10 @@ export interface HttpClientConfig<S extends SchemaRecord = SchemaRecord>
   commitOutbox?: DurableWriteStore;
   /** Compatibility input and internal child-client identity seam. */
   commitOutboxScope?: CommitOutboxScope;
-  /** Which transport carries this client's traffic. */
+  /**
+   * Which transport carries this client's traffic. Defaults to WebSocket for
+   * a scoped `session` and HTTP for an API key or direct auth token.
+   */
   transport?: 'websocket' | 'http' | undefined;
   /** @internal Exact receipt phases observed while dispatching one HTTP commit. */
   onCommitReceipt?: (observation: {