import type { HttpEffect } from "alchemy/Http";
import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as Deferred from "effect/Deferred";
import * as Duration from "effect/Duration";
import * as Effect from "effect/Effect";
import * as Effectable from "effect/Effectable";
import * as Exit from "effect/Exit";
import type * as Headers from "effect/http/Headers";
import * as HttpClient from "effect/http/HttpClient";
import * as HttpClientRequest from "effect/http/HttpClientRequest";
import { HttpServerRequest } from "effect/http/HttpServerRequest";
import * as HttpServerResponse from "effect/http/HttpServerResponse";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Queue from "effect/Queue";
import * as Rpc from "effect/rpc/Rpc";
import * as RpcClient from "effect/rpc/RpcClient";
import * as RpcClientError from "effect/rpc/RpcClientError";
import * as RpcGroup from "effect/rpc/RpcGroup";
import * as RpcMessage from "effect/rpc/RpcMessage";
import type * as RpcMiddleware from "effect/rpc/RpcMiddleware";
import * as RpcSerialization from "effect/rpc/RpcSerialization";
import * as RpcServer from "effect/rpc/RpcServer";
import * as Schema from "effect/Schema";
import type * as Scope from "effect/Scope";
import * as Socket from "effect/socket/Socket";
import * as Stream from "effect/Stream";
import * as Tracer from "effect/Tracer";
import type * as Aggregate from "./Aggregate.ts";
import * as Command from "./Command.ts";
import { DefinitionError, NotInModel, Unreadable, UnroutedCommand } from "./DefinitionError.ts";
import { type Filter, matches } from "./Filter.ts";
import { decodeEnvelope } from "./Kernel.ts";
import * as Key from "./Key.ts";
import * as Middleware from "./Middleware.ts";
import * as Model from "./Model.ts";
import {
type AggregateStore,
captureContext,
type StreamStore,
type Subscription,
type ViewStore,
} from "./Platform.ts";
import type * as Read from "./Read.ts";
import { contractOf, nameOf, readRpcs } from "./ReadRpcs.ts";
import * as RequestContext from "./RequestContext.ts";
import type * as DomainStream from "./Stream.ts";
import type * as View from "./View.ts";
import * as Watch from "./Watch.ts";
/**
* What an Api exposes: commands (writes); views, streams, and aggregates that
* declare a `read` contract (reads).
*/
export type Servable = Command.Any | View.Any | Aggregate.Any | DomainStream.Any;
/** The names of the commands a model holds: their tags. */
export type CommandName<M extends Model.Any> = M["commands"][number]["tag"];
/** The names of the views a model holds. */
export type ViewName<M extends Model.Any> = M["views"][number]["viewName"];
/** The names of the streams a model holds. */
export type StreamName<M extends Model.Any> = M["streams"][number]["streamName"];
/** The names of the aggregates a model holds that declare `read`, so an Api may serve them. */
export type AggregateName<M extends Model.Any> = ReadableName<M["aggregates"][number]>;
/** An aggregate's name, unless its type says it declared no `read`. */
type ReadableName<A> = A extends Aggregate.Any
? [A["definition"]["read"]] extends [undefined]
? never
: A["aggregateName"]
: never;
/**
* What {@link make} takes: the model, and the names of what of it the Api
* serves. A kind it does not list is served whole: every command, view and
* stream of the model, and every aggregate that declares `read`. `[]` serves
* none of a kind.
*/
export interface Options<
M extends Model.Any,
C extends ReadonlyArray<CommandName<M>>,
V extends ReadonlyArray<ViewName<M>>,
S extends ReadonlyArray<StreamName<M>>,
A extends ReadonlyArray<AggregateName<M>>,
> {
/** The model the Api is over. */
readonly model: M;
/** The commands a client may send. Every command of the model by default. */
readonly commands?: C;
/** The views a client may read. Every view of the model by default. */
readonly views?: V;
/** The streams a client may read. Every stream of the model by default. */
readonly streams?: S;
/** The aggregates a client may read directly, through their `read` contract. Every one that declares `read` by default. */
readonly aggregates?: A;
}
/** What an Api over `M` serves, from the names it lists. */
export type ServedBy<
M extends Model.Any,
C extends ReadonlyArray<string>,
V extends ReadonlyArray<string>,
S extends ReadonlyArray<string>,
A extends ReadonlyArray<string>,
> =
| Extract<M["commands"][number], { readonly tag: C[number] }>
| Extract<M["views"][number], { readonly viewName: V[number] }>
| Extract<M["streams"][number], { readonly streamName: S[number] }>
| Extract<M["aggregates"][number], { readonly aggregateName: A[number] }>;
type Commands<E extends Servable> = Extract<E, Command.Any>;
type Views<E extends Servable> = Extract<E, View.Any>;
type Streams<E extends Servable> = Extract<E, DomainStream.Any>;
type Aggregates<E extends Servable> = Exclude<E, Command.Any | View.Any | DomainStream.Any>;
// ---------------------------------------------------------------- client types
type ContractOf<D> = D extends Read.AnyContract ? D : never;
type RejectionOf<D> = Aggregate.InstanceOf<NonNullable<ContractOf<D>["rejects"]>[number]>;
type MiddlewareOf<D> = NonNullable<ContractOf<D>["middleware"]>;
/** Everything a read can fail with: the declared rejections, the middleware's errors, transport. */
export type ReadError<D> =
| RejectionOf<D>
| Middleware.Errors<MiddlewareOf<D>>
| RpcClientError.RpcClientError;
interface CallOptions {
readonly headers?: Headers.Input;
}
/** The typed client of a view exposed in an Api. */
export interface ViewClient<V extends View.Any> {
/** The key's current state (`null` if it does not exist or the filter excludes it). */
readonly get: (
key: Key.IdOf<View.KeyOf<V>>,
options?: CallOptions & {
/** Wait until the view has applied this write (a command's `stream` and `version`). */
readonly atLeast?: { readonly stream: string; readonly version: number };
readonly where?: Filter<View.StateOf<V>>;
},
) => Effect.Effect<View.StateOf<V> | null, ReadError<V["definition"]> | View.ConsistencyTimeout>;
/**
* The key's state with its cursor, then every change. Ends with a rejection
* when `validate` stops allowing it.
*/
readonly watch: (
key: Key.IdOf<View.KeyOf<V>>,
options?: CallOptions & { readonly where?: Filter<View.StateOf<V>> },
) => Stream.Stream<Read.Snapshot<View.StateOf<V> | null>, ReadError<V["definition"]>>;
/**
* The events the key emitted, each with the state after it: history from
* `after` (a cursor), a {@link Read.CaughtUp} frame, then live events.
*/
readonly events: (
key: Key.IdOf<View.KeyOf<V>>,
options?: CallOptions & {
readonly after?: number;
readonly where?: Filter<View.EventOf<V>>;
},
) => Stream.Stream<
View.Entry<View.StateOf<V>, View.EventOf<V>, Key.IdOf<View.KeyOf<V>>> | Read.CaughtUp,
ReadError<V["definition"]>
>;
/** A page of the key's emitted events. */
readonly list: (
key: Key.IdOf<View.KeyOf<V>>,
options?: CallOptions & {
/** Wait until the view has applied this write (a command's `stream` and `version`). */
readonly atLeast?: { readonly stream: string; readonly version: number };
readonly where?: Filter<View.EventOf<V>>;
readonly order?: "asc" | "desc";
readonly take?: number;
readonly after?: number;
},
) => Effect.Effect<
View.Page<View.Entry<View.StateOf<V>, View.EventOf<V>, Key.IdOf<View.KeyOf<V>>>>,
ReadError<V["definition"]> | View.ConsistencyTimeout
>;
/**
* The key's state and the cursor it is valid at, read together. Render the
* state, then follow `events(key, { after: cursor })`: every later change
* arrives once, and none is missed.
*/
readonly snapshot: (
key: Key.IdOf<View.KeyOf<V>>,
options?: CallOptions & {
/** Wait until the view has applied this write (a command's `stream` and `version`). */
readonly atLeast?: { readonly stream: string; readonly version: number };
readonly where?: Filter<View.StateOf<V>>;
},
) => Effect.Effect<
Read.Snapshot<View.StateOf<V> | null>,
ReadError<V["definition"]> | View.ConsistencyTimeout
>;
}
/** The typed client of a stream exposed in an Api. */
export interface StreamClient<S extends DomainStream.Any> {
/** The key's latest entry, or `null` if nothing was appended. */
readonly peek: (
key: Key.IdOf<DomainStream.KeyOf<S>>,
options?: CallOptions & {
/** Wait until the stream's writer has handled this write (a command's `stream` and `version`). */
readonly atLeast?: { readonly stream: string; readonly version: number };
},
) => Effect.Effect<
DomainStream.Entry<DomainStream.EventOf<S>, Key.IdOf<DomainStream.KeyOf<S>>> | null,
ReadError<S["definition"]> | View.ConsistencyTimeout
>;
/**
* The key's latest entry (`null` before any) with its cursor, then each new
* one. Ends with a rejection when `validate` stops allowing it.
*/
readonly watch: (
key: Key.IdOf<DomainStream.KeyOf<S>>,
options?: CallOptions,
) => Stream.Stream<
Read.Snapshot<DomainStream.Entry<
DomainStream.EventOf<S>,
Key.IdOf<DomainStream.KeyOf<S>>
> | null>,
ReadError<S["definition"]>
>;
/** The key's entries from `after` (a cursor), a {@link Read.CaughtUp} frame, then live ones. */
readonly events: (
key: Key.IdOf<DomainStream.KeyOf<S>>,
options?: CallOptions & {
readonly after?: number;
readonly where?: Filter<DomainStream.EventOf<S>>;
},
) => Stream.Stream<
DomainStream.Entry<DomainStream.EventOf<S>, Key.IdOf<DomainStream.KeyOf<S>>> | Read.CaughtUp,
ReadError<S["definition"]>
>;
/** A page of the key's entries. */
readonly list: (
key: Key.IdOf<DomainStream.KeyOf<S>>,
options?: CallOptions & {
readonly where?: Filter<DomainStream.EventOf<S>>;
readonly order?: "asc" | "desc";
readonly take?: number;
readonly after?: number;
},
) => Effect.Effect<
View.Page<DomainStream.Entry<DomainStream.EventOf<S>, Key.IdOf<DomainStream.KeyOf<S>>>>,
ReadError<S["definition"]>
>;
}
/** A committed event of an aggregate, as a client receives it. */
export interface Recorded<E, Id> {
readonly event: E;
readonly envelope: Aggregate.Envelope<Id>;
}
/** The typed client of an aggregate exposed in an Api (through its `read` contract). */
export interface AggregateClient<A extends Aggregate.Any> {
/** The instance's current state. */
readonly get: (
key: Aggregate.IdOf<A>,
options?: CallOptions,
) => Effect.Effect<Aggregate.StateOf<A>, ReadError<A["definition"]["read"]>>;
/** The instance's state with its cursor, then its state after every commit. */
readonly watch: (
key: Aggregate.IdOf<A>,
options?: CallOptions,
) => Stream.Stream<Read.Snapshot<Aggregate.StateOf<A>>, ReadError<A["definition"]["read"]>>;
/**
* The instance's committed events: history from `after` (a cursor), a
* {@link Read.CaughtUp} frame, then live.
*/
readonly events: (
key: Aggregate.IdOf<A>,
options?: CallOptions & { readonly after?: number },
) => Stream.Stream<
Recorded<Aggregate.EventOf<A>, Aggregate.IdOf<A>> | Read.CaughtUp,
ReadError<A["definition"]["read"]>
>;
}
/** How a command is sent: its idempotency key and the call's headers. */
export interface CommandOptions extends CallOptions {
/** A resend with the same id returns the first receipt instead of deciding again. */
readonly commandId?: string;
}
/** The input and options after a command's target. The input may be left out when it has no required field. */
type CommandArgs<Input> = {} extends Input
? [input?: Input, options?: CommandOptions]
: [input: Input, options?: CommandOptions];
/** The typed client of a command exposed in an Api: `bank.WithdrawMoney(target, input, options)`. */
export type CommandClient<C extends Command.Any> =
C["rpc"] extends Rpc.Rpc<
infer _Tag,
infer Payload,
infer Success,
infer Error,
infer Middleware,
infer _Requires
>
? Payload["Type"] extends { readonly target: infer Target; readonly input: infer Input }
? (
target: Target,
...args: CommandArgs<Input>
) => Effect.Effect<
Success["Type"],
| Error["Type"]
| Middleware["error"]["Type"]
| Middleware["~ClientError"]
| RpcClientError.RpcClientError,
| Payload["EncodingServices"]
| Success["DecodingServices"]
| Error["DecodingServices"]
| Middleware["error"]["DecodingServices"]
>
: never
: never;
/**
* The typed client of an Api: commands as methods (`bank.WithdrawMoney(...)`),
* views and aggregates as namespaces (`bank.AccountSummary.watch(...)`).
*/
export type ApiClient<E extends Servable> = {
readonly [C in Commands<E> as C["tag"]]: CommandClient<C>;
} & {
readonly [V in Views<E> as V["viewName"]]: ViewClient<V>;
} & {
readonly [S in Streams<E> as S["streamName"]]: StreamClient<S>;
} & {
readonly [A in Aggregates<E> as A["aggregateName"]]: AggregateClient<A>;
};
/** Type-level identity of an Api's client service. */
export interface ClientKey<Name extends string> {
readonly "~alchemy/Domain/Api/Client": Name;
}
/** What `yield* MyApi` gives a Worker: the Api served over HTTP. */
export interface ApiServer {
/** Use as the Worker's `fetch`. Commands and reads over HTTP; live reads over WebSockets. */
readonly fetch: HttpEffect;
}
/**
* The class type returned by {@link make}. The class is itself an Effect:
* `yield* MyApi` serves it, requiring the hosted Domain and the Layers of every
* middleware what it serves declares.
*/
export interface ApiClass<
Name extends string,
Serves extends ReadonlyArray<Servable>,
> extends Effect.Effect<ApiServer, never, Model.Internals | MiddlewareServices<Serves>> {
new (_: never): {};
readonly kind: "Api";
readonly apiName: Name;
/** The model this Api is over. */
readonly model: Model.Any;
/** The commands, views, streams and aggregates this Api serves. */
readonly serves: Serves;
/** The command classes this Api exposes, in the order it lists them. */
readonly commands: ReadonlyArray<Commands<Serves[number]>>;
/**
* One Schema for every rejection this Api's commands declare: a union of the
* rejection classes, each once, decoding to class instances as the client
* fails with them. `Schema.Never` when no command rejects.
*/
readonly rejections: RejectionUnion<Commands<Serves[number]>["rejects"][number]>;
/** The underlying Effect RPC group. */
readonly group: RpcGroup.RpcGroup<Rpc.Any>;
/**
* A typed client. Provide a protocol: {@link protocolHttp},
* {@link protocolWebSocket} or {@link protocolInProcess}.
*/
readonly client: Effect.Effect<
ApiClient<Serves[number]>,
never,
Scope.Scope | RpcClient.Protocol | MiddlewareClients<Serves>
>;
/** The client as a service, for code that uses it without owning the connection. */
readonly Client: Context.Service<ClientKey<Name>, ApiClient<Serves[number]>>;
/** Build {@link Client} for the life of the Layer, over the protocol provided to it. */
readonly layerClient: Layer.Layer<
ClientKey<Name>,
never,
RpcClient.Protocol | MiddlewareClients<Serves>
>;
/** {@link client} over {@link protocolHttp}. */
readonly clientHttp: (
url: string,
) => Effect.Effect<
ApiClient<Serves[number]>,
never,
Scope.Scope | HttpClient.HttpClient | MiddlewareClients<Serves>
>;
/** {@link layerClient} over {@link protocolHttp}. */
readonly layerClientHttp: (
url: string,
) => Layer.Layer<ClientKey<Name>, never, HttpClient.HttpClient | MiddlewareClients<Serves>>;
/** {@link client} over {@link protocolWebSocket}. */
readonly clientWebSocket: (
url: string,
) => Effect.Effect<
ApiClient<Serves[number]>,
never,
Scope.Scope | HttpClient.HttpClient | Socket.WebSocketConstructor | MiddlewareClients<Serves>
>;
/** {@link layerClient} over {@link protocolWebSocket}. */
readonly layerClientWebSocket: (
url: string,
) => Layer.Layer<
ClientKey<Name>,
never,
HttpClient.HttpClient | Socket.WebSocketConstructor | MiddlewareClients<Serves>
>;
/** {@link client} over {@link protocolInProcess}. In a Worker, build it per request. */
readonly clientInProcess: Effect.Effect<
ApiClient<Serves[number]>,
never,
Scope.Scope | Model.Internals | MiddlewareServices<Serves> | MiddlewareClients<Serves>
>;
/** {@link layerClient} over {@link protocolInProcess}. */
readonly layerClientInProcess: Layer.Layer<
ClientKey<Name>,
never,
Model.Internals | MiddlewareServices<Serves> | MiddlewareClients<Serves>
>;
}
type EntryMiddleware<E> = E extends Command.Any
? E["middleware"][number]
: E extends View.Any | DomainStream.Any
? NonNullable<E["definition"]["middleware"]>[number]
: E extends Aggregate.Any
? NonNullable<NonNullable<E["definition"]["read"]>["middleware"]>[number]
: never;
/** The middleware services the server needs for every entry. */
type MiddlewareServices<Serves extends ReadonlyArray<Servable>> =
EntryMiddleware<Serves[number]> extends infer M
? M extends RpcMiddleware.AnyService
? M["Identifier"]
: never
: never;
/** The client-side middleware every entry needs (e.g. attaching a session token). */
type MiddlewareClients<Serves extends ReadonlyArray<Servable>> =
EntryMiddleware<Serves[number]> extends infer M
? M extends RpcMiddleware.AnyService
? M extends { readonly requiredForClient: true }
? RpcMiddleware.ForClient<M["Identifier"]>
: never
: never
: never;
const rpcsOf = (entry: Servable): ReadonlyArray<Rpc.Any> =>
entry.kind === "Command" ? [entry.rpc] : Object.values(readRpcs(entry));
// ---------------------------------------------------------------- handlers
/**
* Only an entry's declared errors are public. Anything else (an
* infrastructure error, an undeclared rejection) becomes a defect, so it
* never leaks as a typed error the client cannot decode.
*/
const declaredOnly = (rpc: Rpc.Any) => {
const props = rpc as Rpc.AnyWithProps;
const isDeclared = Schema.is(props.errorSchema);
const success = props.successSchema as Schema.Top & { readonly error?: Schema.Top };
const isDeclaredInStream = success.error ? Schema.is(success.error) : isDeclared;
return {
effect: <A, E, R>(effect: Effect.Effect<A, E, R>) =>
Effect.catchIf(
effect,
(e) => !isDeclared(e),
(e) => Effect.die(e),
),
stream: <A, E, R>(stream: Stream.Stream<A, E, R>) =>
Stream.catchIf(
stream,
(e) => !isDeclaredInStream(e),
(e) => Stream.die(e),
),
};
};
/** The wire payload of a command: its target, an optional command id, and its input. */
interface CommandPayload {
readonly target: string;
readonly commandId?: string;
readonly input: object;
}
interface ReadPayload {
readonly key: string;
readonly where?: unknown;
readonly atLeast?: { readonly stream: string; readonly version: number };
readonly after?: number;
readonly order?: "asc" | "desc";
readonly take?: number;
}
const caughtUpAt = (seq: number): Read.CaughtUp => ({ _tag: "CaughtUp", cursor: seq });
/**
* A key's events from `start`, with a `CaughtUp` frame after its history: the
* events up to `end`, the key's `seq` when the read began. `keep` judges and
* filters each event after the end is found, so a filtered-out last event
* still ends the history.
*/
const withCaughtUp = <A>(
start: number,
end: number,
events: Stream.Stream<A, unknown>,
seqOf: (event: A) => number,
keep: (event: A) => Effect.Effect<ReadonlyArray<unknown>, unknown>,
): Stream.Stream<unknown, unknown> => {
let sent = start >= end;
const rest = events.pipe(
Stream.mapEffect((event) =>
keep(event).pipe(
Effect.map((out) => {
if (sent || seqOf(event) < end) return out;
sent = true;
return [...out, caughtUpAt(seqOf(event))];
}),
),
),
Stream.flatMap((out) => Stream.fromIterable(out)),
);
return start >= end ? Stream.concat(Stream.succeed(caughtUpAt(start)), rest) : rest;
};
type Handler = (input: never) => unknown;
/**
* The first thing an Api lists that it cannot serve: a name its model does
* not hold, or an aggregate without a `read` contract. The type of the
* options rules both out; this catches a model typed as `Model.Any`.
*/
/** Why an Api cannot serve something it lists. */
type Unservable = NotInModel | Unreadable;
const notInModel = (
_apiModel: Model.Any,
unresolved: ReadonlyArray<Unservable>,
): DefinitionError | undefined =>
unresolved.length === 0 ? undefined : new DefinitionError({ reason: unresolved[0]! });
const handlersOf = (
apiModel: Model.Any,
entries: ReadonlyArray<Servable>,
unresolved: ReadonlyArray<Unservable>,
): Effect.Effect<Record<string, Handler>, never, Model.Internals> =>
Effect.gen(function* () {
const problem = notInModel(apiModel, unresolved);
if (problem) return yield* Effect.die(problem);
const internals = yield* Model.Internals;
const handlers: Record<string, Handler> = {};
for (const entry of entries) {
if (entry.kind === "Command") {
const aggregate = internals.commands.get(entry.tag);
if (!aggregate) {
return yield* Effect.die(
new DefinitionError({ reason: new UnroutedCommand({ command: entry.tag }) }),
);
}
const declared = declaredOnly(entry.rpc);
// Runs inside the command's middleware, so the context it provides
// (the session's actor) travels with the command to its aggregate.
handlers[entry.tag] = ({ target, commandId, input }: CommandPayload) =>
declared.effect(
// oxlint-disable-next-line effecttsgo/new-schema-class -- `make` on a generic command class loses its instance type
aggregate.send(target, new entry(input), { commandId }).pipe(
Effect.map((receipt) => ({
reply: receipt.reply,
stream: receipt.stream,
version: receipt.version,
})),
),
);
continue;
}
// Serving an aggregate's state without its read contract would skip its middleware.
if (entry.kind === "Aggregate" && !entry.definition.read) {
return yield* Effect.die(
new DefinitionError({ reason: new Unreadable({ aggregate: entry.aggregateName }) }),
);
}
const name = nameOf(entry);
const rpcs = readRpcs(entry);
const validate = contractOf(entry).validate as
| ((request: Read.Request<unknown>, state: unknown) => Effect.Effect<void, unknown>)
| undefined;
const check = (mode: Read.Mode, key: unknown) => (state: unknown) =>
validate ? validate({ mode, key }, state) : Effect.void;
const effect =
(rpc: Rpc.Any, handle: (payload: ReadPayload) => Effect.Effect<unknown, unknown>) =>
(payload: ReadPayload) =>
declaredOnly(rpc).effect(handle(payload));
const stream =
(rpc: Rpc.Any, handle: (payload: ReadPayload) => Stream.Stream<unknown, unknown>) =>
(payload: ReadPayload) =>
declaredOnly(rpc).stream(handle(payload));
if (entry.kind === "Stream") {
const host = internals.streamHosts.get(name)!;
const key = entry.definition.key;
const refOf = (id: string) => Key.refOf(key, id);
const latest = (id: string) =>
host.peek(refOf(id)).pipe(Effect.orDie, Effect.map(Option.getOrNull));
handlers[`${name}.peek`] = effect(rpcs.get, ({ key: id, atLeast }) =>
host.peek(refOf(id), { atLeast }).pipe(
Effect.flatMap((found) => {
const entry = Option.getOrNull(found);
return check("get", refOf(id))(entry).pipe(Effect.as(entry));
}),
),
);
handlers[`${name}.watch`] = stream(rpcs.watch, ({ key: id }) =>
host.watch(refOf(id)).pipe(
Stream.mapEffect((found) => {
const entry = Option.getOrNull(found);
return check(
"watch",
refOf(id),
)(entry).pipe(Effect.as({ state: entry, cursor: entry?.envelope.seq ?? 0 }));
}),
),
);
handlers[`${name}.events`] = stream(rpcs.events, ({ key: id, after, where }) => {
const start = after ?? 0;
return Stream.unwrap(
latest(id).pipe(
Effect.map((last) =>
withCaughtUp(
start,
last?.envelope.seq ?? 0,
host.events(refOf(id), { after: start }),
(entry) => entry.envelope.seq,
// Each entry is judged as the key's latest entry at that point.
(entry) =>
matches(where as Filter<unknown> | undefined, entry.event)
? check("events", refOf(id))(entry).pipe(Effect.as([entry]))
: Effect.succeed([]),
),
),
),
);
});
handlers[`${name}.list`] = effect(rpcs.list!, ({ key: id, where, order, take, after }) =>
latest(id).pipe(
Effect.flatMap((entry) => check("list", refOf(id))(entry)),
Effect.andThen(
host.list(refOf(id), {
where: where as Filter<unknown> | undefined,
order,
take,
after,
}),
),
),
);
continue;
}
if (entry.kind === "View") {
const host = internals.viewHosts.get(name)!;
const key = entry.definition.key;
const refOf = (id: string) => Key.refOf(key, id);
const visible = (state: unknown, where: unknown) =>
state !== null && matches(where as Filter<unknown> | undefined, state) ? state : null;
handlers[`${name}.get`] = effect(rpcs.get, ({ key: id, atLeast, where }) =>
host.query(refOf(id), { atLeast }).pipe(
Effect.flatMap((found) => {
const state = Option.getOrNull(found);
return check("get", refOf(id))(state).pipe(Effect.as(visible(state, where)));
}),
),
);
const viewStore = internals.views.get(name)!;
// From the stored snapshots, so each state comes with the seq it is valid at.
handlers[`${name}.watch`] = stream(rpcs.watch, ({ key: id, where }) =>
viewStore.changes(id).pipe(
Stream.mapEffect((snapshot) => {
const state =
snapshot.state === null
? null
: internals.kernel.decodeViewState(entry, snapshot.state);
return check(
"watch",
refOf(id),
)(state).pipe(Effect.as({ state: visible(state, where), cursor: snapshot.seq }));
}),
),
);
handlers[`${name}.events`] = stream(rpcs.events, ({ key: id, after, where }) => {
const start = after ?? 0;
return Stream.unwrap(
viewStore.read(id).pipe(
Effect.map((snapshot) =>
withCaughtUp(
start,
snapshot.seq,
host.events(refOf(id), { after: start }),
(entry) => entry.envelope.seq,
(entry) =>
matches(where as Filter<unknown> | undefined, entry.event)
? check("events", refOf(id))(entry.state).pipe(Effect.as([entry]))
: Effect.succeed([]),
),
),
),
);
});
handlers[`${name}.snapshot`] = effect(rpcs.snapshot!, ({ key: id, atLeast, where }) =>
host
.snapshot(refOf(id), { atLeast })
.pipe(
Effect.flatMap(({ state, cursor }) =>
check(
"get",
refOf(id),
)(state).pipe(Effect.as({ state: visible(state, where), cursor })),
),
),
);
handlers[`${name}.list`] = effect(
rpcs.list!,
({ key: id, atLeast, where, order, take, after }) =>
host.query(refOf(id), { atLeast }).pipe(
Effect.flatMap((found) => found.pipe(Option.getOrNull, check("list", refOf(id)))),
Effect.andThen(
host.list(refOf(id), {
where: where as Filter<unknown> | undefined,
order,
take,
after,
}),
),
),
);
continue;
}
const store = internals.aggregates.get(name)!;
const refOf = (id: string) => ({ aggregate: name, id });
const stateOf = (json: unknown) => internals.kernel.decodeState(entry, json);
handlers[`${name}.get`] = effect(rpcs.get, ({ key: id }) =>
store.state(id).pipe(
Effect.flatMap(({ state }) => {
const decoded = stateOf(state);
return check("get", refOf(id))(decoded).pipe(Effect.as(decoded));
}),
),
);
handlers[`${name}.watch`] = stream(rpcs.watch, ({ key: id }) =>
store.changes(id).pipe(
Stream.mapEffect(({ state, version }) => {
const decoded = stateOf(state);
return check(
"watch",
refOf(id),
)(decoded).pipe(Effect.as({ state: decoded, cursor: version }));
}),
),
);
handlers[`${name}.events`] = stream(rpcs.events, ({ key: id, after }) => {
const start = after ?? 0;
return Stream.unwrap(
store.state(id).pipe(
Effect.map(({ version }) =>
withCaughtUp(
start,
version,
store.tail(id, start),
(stored) => stored.envelope.seq,
// Judged against the instance's state now, since events carry no state.
(stored) =>
store.state(id).pipe(
Effect.flatMap(({ state }) => check("events", refOf(id))(stateOf(state))),
Effect.andThen(internals.kernel.decodeEvent(stored.event)),
Effect.map((event) => [{ event, envelope: decodeEnvelope(stored.envelope) }]),
),
),
),
),
);
});
}
return handlers;
});
// ---------------------------------------------------------------- live reads
/** The query parameter carrying a live read's request (a WebSocket upgrade cannot carry a body). */
const LIVE_PARAM = "read";
/**
* A live read as the client sends it: the Effect RPC request's id, tag and
* payload, plus the cursor to resume from after a reconnect. Never headers:
* a URL ends up in logs, so a live read authenticates with what its upgrade
* request carries (in a browser, its cookies).
*/
const LiveRequest = Schema.Struct({
id: Schema.Union([Schema.String, Schema.Number]),
tag: Schema.String,
payload: Schema.Unknown,
cursor: Schema.optional(Schema.Number),
/** The client's span, as the RPC protocol carries it, so the read joins the caller's trace. */
traceId: Schema.optional(Schema.String),
spanId: Schema.optional(Schema.String),
sampled: Schema.optional(Schema.Boolean),
});
type LiveRequest = typeof LiveRequest.Type;
const decodeLiveRequest = Schema.decodeUnknownOption(Schema.fromJsonString(LiveRequest));
/** The live read the current request asks for, if its query parameter decodes. */
const liveRequestOf = (request: { readonly url: string }): LiveRequest | undefined => {
const raw = new URL(request.url, "http://localhost").searchParams.get(LIVE_PARAM);
return raw === null ? undefined : Option.getOrUndefined(decodeLiveRequest(raw));
};
/**
* Serve live reads (`watch` and `events`) as WebSockets. The read's
* middleware runs here, in the Worker, against the upgrade request's own
* headers (cookies, in a browser); the context it provides travels with
* the subscription to the object that owns the key, which pushes to the
* socket on every commit. A refused read still connects, to deliver its
* typed rejection.
*/
const liveReads = (
entries: ReadonlyArray<Servable>,
internals: Model.Internals["Service"],
middleware: Context.Context<never>,
) => {
const reads = new Map<
string,
{
readonly rpc: Rpc.AnyWithProps;
readonly mode: "watch" | "events";
readonly store?: AggregateStore | ViewStore | StreamStore;
}
>();
for (const entry of entries) {
if (entry.kind === "Command") continue;
const name = nameOf(entry);
const store =
entry.kind === "View"
? internals.views.get(name)
: entry.kind === "Stream"
? internals.streams.get(name)
: internals.aggregates.get(name);
const rpcs = readRpcs(entry);
reads.set(`${name}.watch`, { rpc: rpcs.watch as Rpc.AnyWithProps, mode: "watch", store });
reads.set(`${name}.events`, { rpc: rpcs.events as Rpc.AnyWithProps, mode: "events", store });
}
return Effect.gen(function* () {
const request = yield* HttpServerRequest;
const live = liveRequestOf(request);
const read = live && reads.get(live.tag);
if (!live || !read) return HttpServerResponse.text("Unknown live read", { status: 400 });
if (!read.store?.connect) {
return HttpServerResponse.text("This platform streams live reads as responses", {
status: 501,
});
}
const payload = yield* Schema.decodeUnknownEffect(Schema.toCodecJson(read.rpc.payloadSchema))(
live.payload,
).pipe(Effect.option);
if (Option.isNone(payload))
return HttpServerResponse.text("Invalid live read", { status: 400 });
const { key, where, after } = payload.value as ReadPayload;
yield* Effect.annotateCurrentSpan({ "domain.read": live.tag, "domain.key": String(key) });
// Run the read's middleware, as the RPC server would, around capturing what it provides.
let authorized: Effect.Effect<RequestContext.Json, unknown> = RequestContext.capture;
for (const service of read.rpc.middlewares) {
const run = Context.getUnsafe(middleware, service) as unknown as (
effect: Effect.Effect<RequestContext.Json, unknown>,
options: unknown,
) => Effect.Effect<RequestContext.Json, unknown>;
authorized = run(authorized, {
rpc: read.rpc,
client: new Rpc.ServerClient(0),
requestId: RpcMessage.RequestId(live.id),
headers: request.headers,
payload: payload.value,
});
}
const subscription: Subscription = {
requestId: live.id,
mode: read.mode,
where: where as Subscription["where"],
context: {},
cursor: live.cursor ?? (read.mode === "watch" ? -1 : (after ?? 0)),
};
const judged = yield* authorized.pipe(
Effect.map((context): Subscription => ({ ...subscription, context })),
Effect.catch((error) =>
Watch.refuse(read.rpc, error).pipe(
Effect.orDie,
Effect.map((refused): Subscription => ({ ...subscription, refused })),
),
),
);
return yield* read.store.connect(String(key), judged);
}).pipe(
// A live read continues the trace of the client that opened it, like an RPC call.
(effect) =>
Effect.flatMap(HttpServerRequest, (request) => {
const live = liveRequestOf(request);
return effect.pipe(
Effect.withSpan(`Domain.read ${live?.tag ?? "unknown"}`, {
kind: "server",
...(live?.traceId && live.spanId
? {
parent: Tracer.externalSpan({
traceId: live.traceId,
spanId: live.spanId,
sampled: live.sampled ?? true,
}),
}
: {}),
}),
);
}),
);
};
// ---------------------------------------------------------------- client
type Flat = Record<string, (payload: unknown, options?: CallOptions) => unknown>;
/** Shape the flat Effect RPC client into commands plus view and aggregate namespaces. */
const nest = (entries: ReadonlyArray<Servable>, flat: Flat): unknown => {
const client: Record<string, unknown> = {};
for (const entry of entries) {
if (entry.kind === "Command") {
const send = flat[entry.tag]!;
client[entry.tag] = (
target: unknown,
input: object = {},
{ commandId, ...options }: CommandOptions = {},
) => send({ target, commandId, input }, options);
continue;
}
const name = nameOf(entry);
const call =
(method: string) =>
(key: unknown, options: CallOptions & Record<string, unknown> = {}) => {
const { headers, ...rest } = options;
return flat[`${name}.${method}`]!({ key, ...rest }, { headers });
};
client[name] =
entry.kind === "View"
? {
get: call("get"),
watch: call("watch"),
events: call("events"),
list: call("list"),
snapshot: call("snapshot"),
}
: entry.kind === "Stream"
? { peek: call("peek"), watch: call("watch"), events: call("events"), list: call("list") }
: { get: call("get"), watch: call("watch"), events: call("events") };
}
return client;
};
/**
* Serves an Api in the caller's process and connects a client to it. Messages
* are encoded as on the wire but never leave memory.
*/
const makeProtocolInProcess = (
model: Model.Any,
entries: ReadonlyArray<Servable>,
unresolved: ReadonlyArray<Unservable>,
group: RpcGroup.RpcGroup<Rpc.Any>,
): Layer.Layer<RpcClient.Protocol, never, Model.Internals> =>
Layer.effect(
RpcClient.Protocol,
Effect.gen(function* () {
const codecFor = Schema.toCodecJson as RpcSerialization.CodecFor;
const disconnects = yield* Queue.unbounded<number>();
const clientIds = new Set<number>();
let toServer = (_: number, __: RpcMessage.FromClientEncoded): Effect.Effect<void> =>
Effect.void;
let toClient = (_: number, __: RpcMessage.FromServerEncoded): Effect.Effect<void> =>
Effect.void;
const server = yield* RpcServer.Protocol.make((write) => {
toServer = write;
return Effect.succeed({
disconnects,
send: (clientId: number, response: RpcMessage.FromServerEncoded) =>
toClient(clientId, response),
end: () => Effect.void,
clientIds: Effect.sync(() => new Set(clientIds) as ReadonlySet<number>),
initialMessage: Effect.succeedNone,
supportsAck: true,
supportsTransferables: false,
supportsSpanPropagation: true,
supportsNotifications: false,
codecFor,
});
});
const protocol = yield* RpcClient.Protocol.make((write) => {
toClient = write;
return Effect.succeed({
send: (clientId: number, request: RpcMessage.FromClientEncoded) =>
toServer(clientId, request),
supportsAck: true,
supportsTransferables: false,
codecFor,
});
});
const handlers = yield* handlersOf(model, entries, unresolved);
// The middleware services in the caller's scope run for every request.
yield* RpcServer.make(group).pipe(
Effect.provide(
Layer.mergeAll(
Layer.succeed(RpcServer.Protocol, server),
group.toLayer(handlers as never) as Layer.Layer<never>,
),
),
Effect.forkScoped,
);
return RpcClient.Protocol.of({
...protocol,
run: (clientId, write) =>
Effect.suspend(() => {
clientIds.add(clientId);
return protocol.run(clientId, write);
}).pipe(
Effect.onExit(() => {
clientIds.delete(clientId);
return Queue.offer(disconnects, clientId);
}),
),
});
}),
);
// The names an Api lists that its model does not hold.
const Unresolved = Symbol.for("alchemy/Domain/Api/Unresolved");
// A class so `class BankApi extends Domain.Api(...) {}` works.
const build = (
name: string,
model: Model.Any,
entries: ReadonlyArray<Servable>,
unresolved: ReadonlyArray<Unservable>,
group: RpcGroup.RpcGroup<Rpc.Any>,
): unknown => {
const client = RpcClient.make(group).pipe(
Effect.map((flat) => nest(entries, flat as unknown as Flat)),
);
const Client = Context.Service<ClientKey<string>, unknown>()(`alchemy/Domain/Api/${name}/Client`);
const commands = entries.filter((entry): entry is Command.Any => entry.kind === "Command");
const rejectionClasses = [...new Set(commands.flatMap((command) => command.rejects))];
const rejections = rejectionClasses.length === 0 ? Schema.Never : Schema.Union(rejectionClasses);
// Serve the Api over HTTP (Effect RPC, NDJSON), with live reads over WebSockets.
const serve = Effect.gen(function* () {
const handlers = yield* handlersOf(model, entries, unresolved);
// The middleware services (declared in the Api's requirements), for every request.
const middleware = yield* captureContext();
const layer = Layer.mergeAll(
group.toLayer(handlers as never),
RpcSerialization.layerNdjson,
Layer.succeedContext(middleware),
);
// One server per request: Workers forbid sharing I/O objects across requests.
const rpc = RpcServer.toHttpEffect(group).pipe(Effect.flatten, Effect.provide(layer));
const live = liveReads(entries, yield* Model.Internals, middleware);
const fetch = Effect.gen(function* () {
const request = yield* HttpServerRequest;
return request.headers.upgrade?.toLowerCase() === "websocket" ? yield* live : yield* rpc;
}) as unknown as HttpEffect;
return { fetch };
});
// The client for the life of the caller's scope, over the given protocol.
const clientOver = <R>(protocol: Layer.Layer<RpcClient.Protocol, never, R>) =>
Effect.flatMap(Layer.build(protocol), (context) => Effect.provide(client, context));
const layerClient = Layer.effect(Client, client);
const inProcess = makeProtocolInProcess(model, entries, unresolved, group);
return Object.assign(
class {},
// The class is an Effect: `yield* MyApi` serves it.
Effectable.Prototype({ label: `alchemy/Domain/Api<${name}>`, evaluate: () => serve }),
{
kind: "Api" as const,
apiName: name,
model,
serves: entries,
[Unresolved]: unresolved,
commands,
rejections,
group,
client,
Client,
layerClient,
clientHttp: (url: string) => clientOver(protocolHttp(url)),
layerClientHttp: (url: string) => layerClient.pipe(Layer.provide(protocolHttp(url))),
clientWebSocket: (url: string) => clientOver(protocolWebSocket(url)),
layerClientWebSocket: (url: string) =>
layerClient.pipe(Layer.provide(protocolWebSocket(url))),
clientInProcess: clientOver(inProcess),
layerClientInProcess: layerClient.pipe(Layer.provide(inProcess)),
},
);
};
/**
* The public surface of a domain for one kind of client: the commands it may
* send, and the views and aggregates (with a `read` contract) it may read.
* Nothing in an Api needs a handler. The class is an Effect: `yield* MyApi`
* gives a Worker its `fetch`. Call it with a typed client over
* `Domain.protocolHttp`, `Domain.protocolWebSocket` or
* `Domain.protocolInProcess`, or with `clientHttp`, `clientWebSocket` or
* `clientInProcess`, which provide them.
*
* ### Declaring an Api
* **Example:** What customers may reach
* ```typescript
* import * as Domain from "@alchemy.run/domain";
* import { Account, DepositMoney, WithdrawMoney } from "./Account.ts";
* import { AccountSummary } from "./AccountSummary.ts";
* import { Bank } from "./Bank.ts";
*
* // Serving something Bank does not hold is a type error; nothing unlisted is served.
* export class CustomerApi extends Domain.Api("CustomerApi", {
* model: Bank,
* commands: ["DepositMoney", "WithdrawMoney"],
* views: ["AccountSummary"],
* aggregates: ["Account"],
* }) {}
* ```
*
* ### Serving it from a Worker
* **Example:** The Api as a Worker's fetch
* ```typescript
* import * as Cloudflare from "@alchemy.run/cloudflare";
* import * as DomainCloudflare from "@alchemy.run/cloudflare/Domain";
* import * as Effect from "effect/Effect";
* import * as Layer from "effect/Layer";
* import { Bank, BankPolicies } from "./Bank.ts";
* import { CustomerApi } from "./CustomerApi.ts";
* import { SessionLive } from "./Session.ts";
*
* const BankLive = SessionLive.pipe(
* Layer.provideMerge(Bank.layer(BankPolicies)),
* Layer.provide(DomainCloudflare.layerDurableObjects()),
* );
*
* export default class BankWorker extends Cloudflare.Worker<BankWorker>()(
* "BankWorker",
* { main: import.meta.url },
* Effect.gen(function* () {
* const api = yield* CustomerApi;
* return { fetch: api.fetch };
* }).pipe(Effect.provide(BankLive)),
* ) {}
* ```
*
* ### Calling it
* `Domain.protocolWebSocket` sends commands, `get` and `list` over HTTP, and
* opens a WebSocket for each `watch` and `events`, pushed by the object that
* owns the key. `Domain.protocolHttp` sends everything over HTTP.
*
* **Example:** A typed client
* ```typescript
* const bank = yield* CustomerApi.client;
* const { reply } = yield* bank.DepositMoney(accountId, { amount: 1_000 });
* const summary = yield* bank.AccountSummary.get(accountId);
* yield* bank.AccountSummary.watch(accountId).pipe(
* Stream.runForEach(({ state }) => Effect.log(state?.balance)),
* );
* ```
*
* ### Calling it in process
* `clientInProcess` serves the Api in the caller's process, through the
* middleware of everything it serves, with nothing sent over a network. Code that has
* already authenticated its caller provides a middleware Layer that trusts it.
*
* **Example:** A webhook that deposits as the system
* ```typescript
* const asSystem = Layer.succeed(Session, (effect) =>
* Effect.provideService(effect, CurrentActor, system("payments-webhook")),
* );
* const bank = yield* CustomerApi.clientInProcess.pipe(Effect.provide(asSystem));
* yield* bank.DepositMoney(accountId, { amount: 1_000 });
* ```
*
* @primitive
*/
export const make = <
const Name extends string,
M extends Model.Any,
const C extends ReadonlyArray<CommandName<M>> = ReadonlyArray<CommandName<M>>,
const V extends ReadonlyArray<ViewName<M>> = ReadonlyArray<ViewName<M>>,
const S extends ReadonlyArray<StreamName<M>> = ReadonlyArray<StreamName<M>>,
const A extends ReadonlyArray<AggregateName<M>> = ReadonlyArray<AggregateName<M>>,
>(
name: Name,
options: Options<M, C, V, S, A>,
): ApiClass<Name, ReadonlyArray<ServedBy<M, C, V, S, A>>> => {
const { model } = options;
// What the Api lists but cannot serve, as the message it dies with when served.
const unresolved: Array<Unservable> = [];
const pick = <T>(
all: ReadonlyArray<T>,
names: ReadonlyArray<string> | undefined,
nameOfT: (t: T) => string,
): ReadonlyArray<T> =>
names === undefined
? all
: names.flatMap((n) => {
const found = all.find((t) => nameOfT(t) === n);
if (found === undefined)
unresolved.push(new NotInModel({ entity: n, model: model.modelName }));
return found === undefined ? [] : [found];
});
const serves: ReadonlyArray<Servable> = [
...pick(model.commands, options.commands, (c) => c.tag),
...pick(model.views, options.views, (v) => v.viewName),
...pick(model.streams, options.streams, (s) => s.streamName),
...pick(model.aggregates, options.aggregates, (a) => a.aggregateName).filter((aggregate) => {
if (aggregate.definition.read !== undefined) return true;
// Unlisted, an aggregate without `read` is simply not served; listed, it is a mistake.
if (options.aggregates !== undefined) {
unresolved.push(new Unreadable({ aggregate: aggregate.aggregateName }));
}
return false;
}),
];
return build(
name,
model,
serves,
unresolved,
RpcGroup.make(...serves.flatMap(rpcsOf)) as unknown as RpcGroup.RpcGroup<Rpc.Any>,
) as ApiClass<Name, ReadonlyArray<ServedBy<M, C, V, S, A>>>;
};
/**
* The HTTP protocol for an Api client (NDJSON, so streams work). Live reads
* are streamed responses, which the platform feeds by polling the key; use
* {@link protocolWebSocket} to have them pushed instead. Requires an
* `HttpClient`, e.g. `FetchHttpClient.layer`.
*/
export const protocolHttp = (
url: string,
): Layer.Layer<RpcClient.Protocol, never, HttpClient.HttpClient> =>
RpcClient.layerProtocolHttp({ url }).pipe(Layer.provide(RpcSerialization.layerNdjson));
/**
* The protocol for a client in the same process as the model. It serves the
* Api right there: the middleware of everything it serves runs, from the Layers
* in scope, and nothing leaves memory. Requires the hosted Domain, like
* serving the Api.
* In a Worker, build it per request.
*/
export const protocolInProcess = <Name extends string, Serves extends ReadonlyArray<Servable>>(
api: ApiClass<Name, Serves>,
): Layer.Layer<RpcClient.Protocol, never, Model.Internals | MiddlewareServices<Serves>> =>
makeProtocolInProcess(
api.model,
api.serves,
(api as unknown as { readonly [Unresolved]: ReadonlyArray<Unservable> })[Unresolved],
api.group,
);
/** A frame of a live read: an Effect RPC message, plus the cursor to resume from. */
const LiveFrame = Schema.StructWithRest(
Schema.Struct({ _tag: Schema.String, cursor: Schema.optional(Schema.Number) }),
[Schema.Record(Schema.String, Schema.Unknown)],
);
const decodeLiveFrame = Schema.decodeUnknownEffect(Schema.fromJsonString(LiveFrame));
/** The RPCs served as live reads. */
const isLiveRead = (tag: string) => tag.endsWith(".watch") || tag.endsWith(".events");
/** Attempts in a row a live read may fail to (re)connect before it fails. */
const RECONNECTS = 8;
/**
* The WebSocket protocol for an Api client. Calls (commands, `get`, `list`)
* go over HTTP like {@link protocolHttp}; every live read (`watch`,
* `events`) opens its own WebSocket, which the Api hands to the object that
* owns the key (on Cloudflare, its Durable Object). Each commit is pushed
* down the socket, so nothing polls and the object hibernates in between. A
* dropped socket reconnects and resumes after the last value it delivered.
*
* A browser cannot set headers on a WebSocket, and a URL ends up in logs,
* so headers client middleware attaches apply to calls only. A live read
* authenticates with what its upgrade request carries: in a browser, the
* cookies of the Api's origin, so serve the app and the Api from one origin
* and keep sessions in an `HttpOnly`, `SameSite` cookie. Requires an
* `HttpClient` and a `Socket.WebSocketConstructor`
* (`Socket.layerWebSocketConstructorGlobal` in browsers and Workers).
*
* **Example:** Watching a view over a WebSocket
* ```typescript
* const BankConnection = CustomerApi.layerClient.pipe(
* Layer.provide(Domain.protocolWebSocket("https://bank.example.com/api")),
* Layer.provide(Layer.mergeAll(FetchHttpClient.layer, Socket.layerWebSocketConstructorGlobal)),
* );
* ```
*/
export const protocolWebSocket = (
url: string,
): Layer.Layer<RpcClient.Protocol, never, HttpClient.HttpClient | Socket.WebSocketConstructor> =>
Layer.effect(
RpcClient.Protocol,
Effect.gen(function* () {
const client = HttpClient.mapRequest(
yield* HttpClient.HttpClient,
HttpClientRequest.prependUrl(url),
);
const http = yield* RpcClient.makeProtocolHttp(client).pipe(
Effect.provide(RpcSerialization.layerNdjson),
);
const constructor = yield* Socket.WebSocketConstructor;
const socketUrl = url.replace(/^http/, "ws");
const writers = new Map<
number,
(message: RpcMessage.FromServerEncoded) => Effect.Effect<void>
>();
const stops = new Map<string, Deferred.Deferred<void>>();
const liveRead = (clientId: number, request: RpcMessage.RequestEncoded) =>
Effect.gen(function* () {
let cursor: number | undefined;
let ended = false;
let failures = 0;
const connect = Effect.gen(function* () {
const live: LiveRequest = {
id: request.id,
tag: request.tag,
payload: request.payload,
cursor,
...(request.traceId && request.spanId
? { traceId: request.traceId, spanId: request.spanId, sampled: request.sampled }
: {}),
};
const socket = yield* Socket.makeWebSocket(
`${socketUrl}?${LIVE_PARAM}=${encodeURIComponent(JSON.stringify(live))}`,
);
const pull = yield* Socket.readerString(socket);
while (!ended) {
for (const text of yield* pull) {
const { cursor: next, ...message } = yield* decodeLiveFrame(text);
failures = 0;
if (next !== undefined) cursor = next;
if (message._tag === "Exit") ended = true;
yield* Effect.suspend(
() =>
writers.get(clientId)?.(message as RpcMessage.FromServerEncoded) ?? Effect.void,
);
}
}
}).pipe(Effect.scoped, Effect.provideService(Socket.WebSocketConstructor, constructor));
while (!ended) {
const exit = yield* Effect.exit(connect);
if (ended) return;
// A close without an `Exit` (a deploy, an evicted object) reconnects and resumes.
if (++failures > RECONNECTS) {
return yield* RpcClientError.RpcClientError.make({
reason: RpcClientError.RpcClientDefect.make({
message: `Live read ${request.tag} lost its connection`,
cause: Exit.isFailure(exit) ? Cause.squash(exit.cause) : undefined,
}),
});
}
yield* Effect.sleep(Duration.millis(Math.min(5_000, 100 * 2 ** failures)));
}
});
return RpcClient.Protocol.of({
run: (clientId, write) =>
Effect.suspend(() => {
writers.set(clientId, write);
return http.run(clientId, write);
}).pipe(Effect.ensuring(Effect.sync(() => writers.delete(clientId)))),
send: (clientId, request, transferables) => {
if (request._tag === "Request" && isLiveRead(request.tag)) {
return Effect.gen(function* () {
const stop = yield* Deferred.make<void>();
stops.set(String(request.id), stop);
yield* Effect.raceFirst(liveRead(clientId, request), Deferred.await(stop)).pipe(
Effect.ensuring(Effect.sync(() => stops.delete(String(request.id)))),
);
});
}
if (request._tag === "Interrupt") {
const stop = stops.get(String(request.requestId));
if (stop) return Deferred.succeed(stop, undefined).pipe(Effect.asVoid);
}
return http.send(clientId, request, transferables);
},
supportsAck: false,
supportsTransferables: false,
codecFor: http.codecFor,
});
}),
);
// ---------------------------------------------------------------- generic helpers
/** The Schema of a union of rejection classes; `Schema.Never` when there are none. */
type RejectionUnion<R> = [R] extends [never]
? typeof Schema.Never
: Schema.Codec<Aggregate.InstanceOf<R>, Schema.Codec.Encoded<R>>;
/**
* Any Api class. Use it to write code that works with every Api, such as a
* helper that turns each command of an Api into a UI action. `ApiClass` does
* not fit there: its client type is exact, so a concrete Api is not an
* `ApiClass<string, ReadonlyArray<Servable>>`.
*
* **Example:** A helper for any Api
* ```typescript
* const tagsOf = <A extends Domain.Api.Any>(api: A): ReadonlyArray<Domain.Api.CommandsOf<A>["tag"]> =>
* api.commands.map((command) => command.tag);
*
* tagsOf(CustomerApi); // ["DepositMoney", "WithdrawMoney"]
* ```
*/
export interface Any {
readonly kind: "Api";
readonly apiName: string;
/** The model the Api is over. */
readonly model: Model.Any;
/** The commands, views, streams and aggregates the Api serves. */
readonly serves: ReadonlyArray<Servable>;
/** The command classes the Api exposes, in order. */
readonly commands: ReadonlyArray<Command.Any>;
/** One Schema for every rejection the Api's commands declare. */
readonly rejections: Schema.Top;
/** The Api's client service. */
readonly Client: Context.Key<ClientKey<string>, unknown>;
}
/** The command classes an Api exposes. */
export type CommandsOf<A extends Any> = A["commands"][number];
/** The rejection classes the commands of an Api declare. */
export type RejectionsOf<A extends Any> = CommandsOf<A>["rejects"][number];
/** The client an Api's `Client` service gives (`yield* MyApi.Client`). */
export type ClientOf<A extends Any> = A["Client"]["Service"];