@akterjs/client 0.0.0-stage → 0.1.1

package/dist/actor-operations.pure.mjs

@@ -0,0 +1,512 @@
+import { inputOf } from "./actor-fields.pure.mjs";
+import { Array, Effect, Option, Record, SchemaAST, String as String$1 } from "effect";
+import { SecureRandom } from "effect/crypto";
+import { RpcSchema } from "effect/rpc";
+// src/actor-operations.pure.ts
+const group = "actors";
+const commandOfKind = (kind) => {
+	const [owner, name] = String$1.split("/")(kind);
+	return Option.match(Option.fromUndefinedOr(name), {
+		onNone: () => [group, kind],
+		onSome: (found) => [owner, found]
+	});
+};
+const subscribe = "/subscribe";
+const declared = [
+	{
+		description: "Run one of an actor's commands and print its reply.",
+		fields: [
+			"actor",
+			"key",
+			"member",
+			"payload",
+			"commandId"
+		],
+		idempotent: false,
+		kind: "call",
+		readOnly: false
+	},
+	{
+		description: "Run one of an actor's queries and print its reply.",
+		fields: [
+			"actor",
+			"key",
+			"member",
+			"payload"
+		],
+		idempotent: true,
+		kind: "query",
+		readOnly: true
+	},
+	{
+		description: "Print an actor's state once.",
+		fields: ["actor", "key"],
+		idempotent: true,
+		kind: "state",
+		readOnly: true
+	},
+	{
+		description: "Print a query's reply, then each new reply as the actor changes, one JSON line each.",
+		fields: [
+			"actor",
+			"key",
+			"member",
+			"payload"
+		],
+		idempotent: true,
+		kind: "watch",
+		readOnly: true
+	},
+	{
+		description: "Create an actor from its create input; fails when it already exists.",
+		fields: [
+			"actor",
+			"key",
+			"payload",
+			"commandId"
+		],
+		idempotent: false,
+		kind: "create",
+		readOnly: false
+	},
+	{
+		description: "Create an actor from its create input unless it already exists.",
+		fields: [
+			"actor",
+			"key",
+			"payload",
+			"commandId"
+		],
+		idempotent: true,
+		kind: "ensure",
+		readOnly: false
+	},
+	{
+		description: "List an actor's files a page at a time, with each path, size, digest and write time.",
+		fields: [
+			"actor",
+			"key",
+			"prefix",
+			"cursor",
+			"limit"
+		],
+		idempotent: true,
+		kind: "files/list",
+		readOnly: true
+	},
+	{
+		description: "List an actor's files a page at a time, with the total bytes they hold.",
+		fields: [
+			"actor",
+			"key",
+			"prefix",
+			"cursor",
+			"limit"
+		],
+		idempotent: true,
+		kind: "files/usage",
+		readOnly: true
+	},
+	{
+		description: "Download one of an actor's files, whole or the byte range offset and length give.",
+		fields: [
+			"actor",
+			"key",
+			"path",
+			"offset",
+			"length"
+		],
+		idempotent: true,
+		kind: "files/download",
+		readOnly: true
+	},
+	{
+		description: "Upload a file for an actor and print its receipt, which a command attaches at a path.",
+		fields: [
+			"actor",
+			"key",
+			"content"
+		],
+		idempotent: false,
+		kind: "files/upload",
+		readOnly: false
+	},
+	{
+		description: "Fork an actor into a new actor at another key: a copy of its state and files at one moment, with none of its work in flight (its jobs, timers and undelivered messages stay with the original). A retry with the same commandId makes one copy.",
+		fields: [
+			"actor",
+			"key",
+			"into",
+			"commandId"
+		],
+		idempotent: false,
+		kind: "fork",
+		readOnly: false
+	},
+	{
+		description: "List an actor's computers, each with its image, size, egress and state.",
+		fields: ["actor", "key"],
+		idempotent: true,
+		kind: "computers/list",
+		readOnly: true
+	},
+	{
+		description: "Copy one file (at most 1 MiB) between an actor and its computer. fromComputer returns a receipt; attach it with an actor command.",
+		fields: [
+			"actor",
+			"key",
+			"computer",
+			"direction",
+			"path",
+			"computerPath"
+		],
+		flag: "computerFiles",
+		idempotent: false,
+		kind: "computers/cp",
+		readOnly: false
+	},
+	{
+		description: "Show one of an actor's computers: its image, size, egress and state.",
+		fields: [
+			"actor",
+			"key",
+			"computer"
+		],
+		idempotent: true,
+		kind: "computers/get",
+		readOnly: true
+	},
+	{
+		description: "Read a page of a computer's log, oldest first; pass the last seq printed as after to read on.",
+		fields: [
+			"actor",
+			"key",
+			"computer",
+			"after",
+			"limit"
+		],
+		idempotent: true,
+		kind: "computers/logs",
+		readOnly: true
+	},
+	{
+		description: "Pause a computer, keeping its memory and disk, and print it.",
+		fields: [
+			"actor",
+			"key",
+			"computer"
+		],
+		idempotent: true,
+		kind: "computers/pause",
+		readOnly: false
+	},
+	{
+		description: "Resume a paused computer and print it; fails while a fork holds it.",
+		fields: [
+			"actor",
+			"key",
+			"computer"
+		],
+		idempotent: true,
+		kind: "computers/resume",
+		readOnly: false
+	},
+	{
+		description: "Stop a computer, keeping its disk, and print it.",
+		fields: [
+			"actor",
+			"key",
+			"computer"
+		],
+		idempotent: true,
+		kind: "computers/stop",
+		readOnly: false
+	},
+	{
+		description: "Delete a computer and its disk. The actor's own jobs make computers; this only removes one.",
+		fields: [
+			"actor",
+			"key",
+			"computer"
+		],
+		idempotent: true,
+		kind: "computers/delete",
+		readOnly: false
+	},
+	{
+		description: "List an actor's durable computer steps, newest first: each one's job, name, computer, command and state, and its exit code once it ran.",
+		fields: [
+			"actor",
+			"key",
+			"limit"
+		],
+		flag: "computerSteps",
+		idempotent: true,
+		kind: "steps/list",
+		readOnly: true
+	},
+	{
+		description: "Show one of an actor's durable computer steps with its output. A step in state unknown may have done its work; reconcile it by its id.",
+		fields: [
+			"actor",
+			"key",
+			"step"
+		],
+		flag: "computerSteps",
+		idempotent: true,
+		kind: "steps/get",
+		readOnly: true
+	},
+	{
+		description: "Load an actor ahead of its first call, so that call answers sooner.",
+		fields: ["actor", "key"],
+		idempotent: true,
+		kind: "warm",
+		readOnly: true
+	}
+];
+const streams = [
+	"files/download",
+	"state",
+	"watch"
+];
+const dangerous = ["computers/delete"];
+const operationOf = ({ description, fields, flag, idempotent, kind, readOnly }) => {
+	const [owner, name] = commandOfKind(kind);
+	const confirm = Array.contains(dangerous, kind);
+	const operation = {
+		annotations: {
+			confirm,
+			destructive: confirm,
+			idempotent,
+			openWorld: false,
+			readOnly
+		},
+		command: [owner, name],
+		description,
+		fields,
+		flag: Option.fromUndefinedOr(flag),
+		id: `${owner}.${name}`,
+		input: inputOf(fields),
+		kind,
+		stream: Array.contains(streams, kind),
+		tool: `${owner}_${name}`
+	};
+	if (kind === "computers/cp") return {
+		...operation,
+		tool: "computers_files"
+	};
+	return operation;
+};
+const unexposedKinds = ["warm"];
+const actorOperations = Array.map(Array.filter(declared, ({ kind }) => !Array.contains(unexposedKinds, kind)), operationOf);
+const tagOf = ({ actor, kind, member }) => {
+	return {
+		call: `${actor}/${member}`,
+		"computers/cp": `${actor}/computer/files`,
+		"computers/delete": `${actor}/computer/delete`,
+		"computers/get": `${actor}/computer/get`,
+		"computers/list": `${actor}/computer/list`,
+		"computers/logs": `${actor}/computer/logs`,
+		"computers/pause": `${actor}/computer/pause`,
+		"computers/resume": `${actor}/computer/resume`,
+		"computers/stop": `${actor}/computer/stop`,
+		create: `${actor}/create`,
+		ensure: `${actor}/ensure`,
+		"files/download": `${actor}/files/download`,
+		"files/list": `${actor}/files/list`,
+		"files/upload": `${actor}/files/upload`,
+		"files/usage": `${actor}/files/usage`,
+		fork: `${actor}/fork`,
+		query: `${actor}/${member}`,
+		state: `${actor}/state${subscribe}`,
+		"steps/get": `${actor}/computer/step`,
+		"steps/list": `${actor}/computer/steps`,
+		warm: `${actor}/warm`,
+		watch: `${actor}/${member}${subscribe}`
+	}[kind];
+};
+const payloadFields = (rpc) => {
+	const names = Option.match(Option.liftPredicate(rpc.payloadSchema.ast, SchemaAST.isObjects), {
+		onNone: () => [],
+		onSome: (ast) => Array.map(ast.propertySignatures, ({ name }) => String(name))
+	});
+	return Array.join(Array.sort(names, String$1.Order), ",");
+};
+const fixedMembers = {
+	create: {
+		fields: "commandId,key,payload",
+		kind: "create",
+		stream: false
+	},
+	ensure: {
+		fields: "commandId,key,payload",
+		kind: "ensure",
+		stream: false
+	},
+	fork: {
+		fields: "commandId,into,key",
+		kind: "fork",
+		stream: false
+	},
+	state: {
+		fields: "key",
+		kind: "state",
+		stream: true
+	},
+	warm: {
+		fields: "key",
+		kind: "warm",
+		stream: false
+	}
+};
+const anyMember = [
+	{
+		fields: "commandId,key,payload",
+		kind: "call",
+		stream: false
+	},
+	{
+		fields: "key,payload",
+		kind: "query",
+		stream: false
+	},
+	{
+		fields: "key,payload",
+		kind: "watch",
+		stream: true
+	}
+];
+const fileRpcs = {
+	"files/download": {
+		fields: "key,length,offset,path",
+		kind: "files/download",
+		stream: true
+	},
+	"files/list": {
+		fields: "cursor,key,limit,prefix",
+		kind: "files/list",
+		stream: false
+	},
+	"files/upload/append": {
+		fields: "bytes,key,offset,upload",
+		kind: "files/upload",
+		stream: false
+	},
+	"files/upload/close": {
+		fields: "bytes,key,upload",
+		kind: "files/upload",
+		stream: false
+	},
+	"files/upload/open": {
+		fields: "key",
+		kind: "files/upload",
+		stream: false
+	},
+	"files/usage": {
+		fields: "cursor,key,limit,prefix",
+		kind: "files/usage",
+		stream: false
+	}
+};
+const computerRpcs = {
+	"computer/delete": {
+		fields: "computer,key",
+		kind: "computers/delete",
+		stream: false
+	},
+	"computer/files": {
+		fields: "computer,computerPath,direction,key,path",
+		kind: "computers/cp",
+		stream: false
+	},
+	"computer/get": {
+		fields: "computer,key",
+		kind: "computers/get",
+		stream: false
+	},
+	"computer/list": {
+		fields: "key",
+		kind: "computers/list",
+		stream: false
+	},
+	"computer/logs": {
+		fields: "after,computer,key,limit",
+		kind: "computers/logs",
+		stream: false
+	},
+	"computer/pause": {
+		fields: "computer,key",
+		kind: "computers/pause",
+		stream: false
+	},
+	"computer/resume": {
+		fields: "computer,key",
+		kind: "computers/resume",
+		stream: false
+	},
+	"computer/step": {
+		fields: "key,step",
+		kind: "steps/get",
+		stream: false
+	},
+	"computer/steps": {
+		fields: "key,limit",
+		kind: "steps/list",
+		stream: false
+	},
+	"computer/stop": {
+		fields: "computer,key",
+		kind: "computers/stop",
+		stream: false
+	}
+};
+const nestedRpcs = {
+	...fileRpcs,
+	...computerRpcs
+};
+const laterMembers = ["computer", "files"];
+const actorRest = /^[^/]+\/(?<rest>.+)$/u;
+const actorTag = /^[^/]+\/(?<member>[^/]+)(?:\/subscribe)?$/u;
+const kindOfRpc = ([tag, rpc]) => {
+	const member = Option.fromUndefinedOr(actorTag.exec(tag)?.groups?.member);
+	const fields = payloadFields(rpc);
+	const stream = RpcSchema.isStreamSchema(rpc.successSchema);
+	const rest = Option.fromUndefinedOr(actorRest.exec(tag)?.groups?.rest);
+	const nested = Option.flatMap(rest, (name) => Record.get(nestedRpcs, name));
+	const candidates = Option.match(Option.filter(member, (name) => !Array.contains(laterMembers, name)), {
+		onNone: () => Option.toArray(nested),
+		onSome: (name) => Option.match(Record.get(fixedMembers, name), {
+			onNone: () => anyMember,
+			onSome: Array.of
+		})
+	});
+	return Option.map(Array.findFirst(candidates, (signature) => signature.fields === fields && signature.stream === stream), (signature) => signature.kind);
+};
+const kindsOf = (requests) => Array.map(Array.fromIterable(requests), ([tag, rpc]) => [tag, kindOfRpc([tag, rpc])]);
+const someField = (name, value) => Option.match(value, {
+	onNone: () => ({}),
+	onSome: (found) => ({ [name]: found })
+});
+const actorRequestOf = (operation) => (input) => Effect.gen(function* buildRequest() {
+	const takes = (name) => Array.contains(operation.fields, name);
+	const minted = SecureRandom.SecureRandom.use((random) => random.uuidV7());
+	const fresh = yield* Effect.when(minted, Effect.succeed(takes("commandId") && Option.isNone(input.commandId)));
+	const commandId = Option.filter(Option.orElse(input.commandId, () => fresh), () => takes("commandId"));
+	const payload = Option.liftPredicate(Option.getOrNull(input.payload), () => takes("payload"));
+	return {
+		payload: {
+			...Record.filter(input.fileFields, (_value, name) => Array.some(operation.fields, (field) => field === name)),
+			...someField("commandId", commandId),
+			...someField("into", Option.filter(input.into, () => takes("into"))),
+			...someField("payload", payload),
+			key: input.key
+		},
+		tag: tagOf({
+			actor: input.actor,
+			kind: operation.kind,
+			member: input.member
+		})
+	};
+});
+export { actorOperations, actorRequestOf, kindsOf, tagOf, unexposedKinds };

package/dist/actor-protocol.layer.d.mts

@@ -0,0 +1,18 @@
+import { Effect, Scope } from "effect";
+import { RpcClientError, RpcMessage } from "effect/rpc";
+import { HttpClient } from "effect/http";
+type Headers = () => Readonly<Record<string, string>>;
+interface ActorProtocolOptions {
+  readonly headers: Headers;
+  readonly http: HttpClient.HttpClient;
+  readonly url: string;
+  readonly webSocket: typeof globalThis.WebSocket;
+}
+declare const actorProtocol: (options: ActorProtocolOptions) => Effect.Effect<{
+  readonly run: (clientId: number, f: (data: RpcMessage.FromServerEncoded) => Effect.Effect<void>) => Effect.Effect<never>;
+  readonly send: (clientId: number, request: RpcMessage.FromClientEncoded, transferables?: ReadonlyArray<globalThis.Transferable>) => Effect.Effect<void, RpcClientError.RpcClientError>;
+  readonly supportsAck: boolean;
+  readonly supportsTransferables: boolean;
+  readonly codecFor: import("effect/rpc/RpcSerialization").CodecFor;
+}, never, import("effect/rpc/RpcSerialization").RpcSerialization | Scope.Scope>;
+export { type ActorProtocolOptions, actorProtocol };

package/dist/actor-protocol.layer.mjs

@@ -0,0 +1,172 @@
+import { trackedFloors } from "./read-floors.pure.mjs";
+import { remoteInterrupts } from "./remote-interrupt.pure.mjs";
+import { Array, Clock, Effect, FiberMap, Latch, Option, Predicate, Record, Ref, Schema, String } from "effect";
+import { RpcClient, RpcClientError, RpcMessage } from "effect/rpc";
+import { Socket } from "effect/socket";
+// src/actor-protocol.layer.ts
+const streamSuffix = "/subscribe";
+const liveProtocol = "akter-rpc";
+const authProtocol = "akter-auth.";
+const authorizationHeader = "authorization";
+const bearerPrefix = "Bearer ";
+const pingEvery = "10 seconds";
+const silentMillis = 25e3;
+const openTimeout = "10 seconds";
+const normalClose = 1e3;
+const ClientProtocolError = Schema.TaggedStruct("ClientProtocolError", {
+	error: RpcClientError.RpcClientError,
+	requestIds: Schema.Array(Schema.Union([Schema.String, Schema.Finite]))
+});
+const JsonText = Schema.fromJsonString(Schema.Unknown);
+const encodeJson = Schema.encodeEffect(JsonText);
+const decodeJson = Schema.decodeEffect(JsonText);
+const utf8 = new globalThis.TextDecoder();
+function serverMessages(values) {
+	return values;
+}
+const textOf = (message) => Effect.orDie(encodeJson(message));
+const tokenOf = (headers) => Option.map(Option.filter(Record.get(headers, authorizationHeader), String.startsWith(bearerPrefix)), String.slice(7));
+const withoutAuthorization = (headers) => Array.filter(Record.toEntries(headers), ([name]) => String.toLowerCase(name) !== authorizationHeader);
+const socketUrl = (url, request) => Effect.map(textOf({
+	...request,
+	headers: []
+}), (text) => {
+	const target = new globalThis.URL(url);
+	target.protocol = String.replace(/^http/u, "ws")(target.protocol);
+	target.searchParams.set("request", text);
+	return target.href;
+});
+const lost = (message, cause) => RpcClientError.RpcClientError.make({ reason: RpcClientError.RpcClientDefect.make({
+	cause,
+	message
+}) });
+const textFrom = (frame) => {
+	if (Predicate.isString(frame)) return frame;
+	return utf8.decode(frame);
+};
+const decodeFrame = (frame) => Effect.mapBoth(decodeJson(textFrom(frame)), {
+	onFailure: (cause) => lost("the live socket sent a frame that isn't RPC JSON", cause),
+	onSuccess: (decoded) => serverMessages(Array.ensure(decoded))
+});
+const opened = ({ headers, url, webSocket }, request) => Effect.gen(function* openLiveSocket() {
+	const sent = headers();
+	const credentials = Option.map(tokenOf(sent), (token) => `${authProtocol}${token}`);
+	const protocols = [liveProtocol, ...Option.toArray(credentials)];
+	const target = yield* socketUrl(url, request);
+	const socket = yield* Socket.fromWebSocket(Effect.acquireRelease(Effect.sync(() => new webSocket(target, protocols)), (native) => Effect.sync(() => {
+		native.close(normalClose);
+	})), { openTimeout });
+	const reader = yield* socket.reader;
+	const writer = yield* socket.writer;
+	const opening = yield* textOf({
+		...request,
+		headers: [...request.headers, ...withoutAuthorization(sent)]
+	});
+	yield* writer.write(opening);
+	return {
+		reader,
+		writer
+	};
+});
+const received = ({ deliver, ended }) => (response) => {
+	if (Predicate.isTagged(response, "Pong")) return Effect.void;
+	if (RpcMessage.isTerminalResponse(response)) return Effect.andThen(deliver(response), Latch.open(ended));
+	return deliver(response);
+};
+const receiving = (live) => {
+	const onFrame = (frame) => Effect.flatMap(decodeFrame(frame), (responses) => Effect.andThen(Effect.flatMap(Clock.currentTimeMillis, (now) => Ref.set(live.seen, now)), Effect.forEach(responses, received(live), { discard: true })));
+	return Effect.forever(Effect.flatMap(live.reader.pull, (frames) => Effect.forEach(frames, onFrame)));
+};
+const pinging = ({ seen, writer }) => Effect.forever(Effect.gen(function* pingLiveSocket() {
+	yield* Effect.sleep(pingEvery);
+	const now = yield* Clock.currentTimeMillis;
+	const last = yield* Ref.get(seen);
+	if (now - last > silentMillis) return yield* lost("the live socket went silent", now - last);
+	const frame = yield* textOf(RpcMessage.constPing);
+	return yield* writer.write(frame);
+}));
+const transportFailure = (failure) => {
+	if (Predicate.isTagged(failure, "RpcClientError")) return failure;
+	return RpcClientError.RpcClientError.make({ reason: failure.reason });
+};
+const liveStream = (options, writers) => ({ deliver, request }) => {
+	const served = Effect.gen(function* serveLiveRequest() {
+		const { reader, writer } = yield* opened(options, request);
+		const ended = yield* Latch.make();
+		const now = yield* Clock.currentTimeMillis;
+		const live = {
+			deliver,
+			ended,
+			reader,
+			seen: yield* Ref.make(now),
+			writer
+		};
+		yield* Effect.acquireRelease(Effect.sync(() => writers.set(request.id, writer)), () => Effect.sync(() => writers.delete(request.id)));
+		yield* Effect.raceFirst(Effect.raceFirst(receiving(live), pinging(live)), ended.await);
+	});
+	return Effect.matchEffect(Effect.scoped(served), {
+		onFailure: (failure) => deliver(ClientProtocolError.make({
+			error: transportFailure(failure),
+			requestIds: [request.id]
+		})),
+		onSuccess: () => Effect.void
+	});
+};
+const liveRequestOf = (message) => {
+	if (Predicate.isTagged(message, "Request") && String.endsWith(streamSuffix)(message.tag)) return Option.some(message);
+	return Option.none();
+};
+const deliveries = (http) => {
+	const delivers = /* @__PURE__ */ new Map();
+	const floors = trackedFloors();
+	const interrupts = remoteInterrupts();
+	const deliverTo = (clientId) => (response) => Option.match(Option.fromNullishOr(delivers.get(clientId)), {
+		onNone: () => Effect.void,
+		onSome: (deliver) => deliver(interrupts.received(clientId, response))
+	});
+	const run = (clientId, deliver) => Effect.ensuring(Effect.suspend(() => {
+		delivers.set(clientId, deliver);
+		return http.run(clientId, (response) => Effect.andThen(Effect.sync(() => {
+			floors.received(clientId, response);
+		}), Effect.suspend(() => deliver(interrupts.received(clientId, response)))));
+	}), Effect.sync(() => delivers.delete(clientId)));
+	return {
+		deliverTo,
+		floors,
+		interrupts,
+		run
+	};
+};
+const actorProtocol = Effect.fnUntraced(function* actorProtocol(options) {
+	const http = yield* RpcClient.makeProtocolHttp(options.http);
+	const lives = yield* FiberMap.make();
+	const writers = /* @__PURE__ */ new Map();
+	const { deliverTo, floors, interrupts, run } = deliveries(http);
+	const serve = liveStream(options, writers);
+	const writeTo = (requestId, message) => Option.match(Option.fromNullishOr(writers.get(requestId)), {
+		onNone: () => Effect.void,
+		onSome: (writer) => Effect.ignore(Effect.flatMap(textOf(message), (frame) => writer.write(frame)))
+	});
+	const send = (clientId, message, transferables) => {
+		const live = liveRequestOf(message);
+		interrupts.sent(clientId, message);
+		if (Option.isSome(live)) {
+			const streamed = serve({
+				deliver: deliverTo(clientId),
+				request: live.value
+			});
+			return Effect.asVoid(FiberMap.run(lives, live.value.id, streamed));
+		}
+		if (Predicate.isTagged(message, "Ack")) return writeTo(message.requestId, message);
+		if (Predicate.isTagged(message, "Interrupt")) return Effect.andThen(writeTo(message.requestId, message), FiberMap.remove(lives, message.requestId));
+		return http.send(clientId, floors.sent(clientId, message), transferables);
+	};
+	return RpcClient.Protocol.of({
+		codecFor: http.codecFor,
+		run,
+		send,
+		supportsAck: true,
+		supportsTransferables: false
+	});
+});
+export { actorProtocol };