@rikalabs/akter 0.1.0-alpha.0

package/dist/testing/cluster.js

@@ -0,0 +1,296 @@
+import { connect, Socket as NetSocket } from "node:net";
+import { Context, Crypto, Duration, Effect, Exit, Fiber, HashRing, Layer, Option, Queue, Redacted, Schedule, Scope, } from "effect";
+import { RunnerAddress, RunnerServer, Runners, RunnerStorage } from "effect/cluster";
+import { NetAddress } from "effect/net";
+import { RpcClient, RpcSerialization, RpcServer } from "effect/rpc";
+import { Socket, SocketServer } from "effect/socket";
+import { SqlClient } from "effect/sql";
+import { InternalActors } from "../runtime/actors.js";
+import { Database } from "../runtime/layer.js";
+import { RunnerWiring } from "../runtime/runner.js";
+import { admissionSharding } from "../runtime/topology/admission.js";
+import { ActorTest, ClusterMember } from "./actor-test.js";
+/** Enough shards that every runner of a small cluster owns several, so actors spread and a killed runner's actors move. */
+const SHARDS = 32;
+/** Shorter than Cluster's defaults so a test sees runner changes within a second; lock timing is the caller's `shardLockExpiration`. */
+const TIMINGS = {
+    refreshAssignmentsInterval: "250 millis",
+    entityMessagePollInterval: "250 millis",
+    sendRetryInterval: "50 millis",
+    entityTerminationTimeout: "2 seconds",
+};
+/** Sessions per pool for each runner unless a cluster says otherwise; three runners hold 24 sessions at most. */
+const RUNNER_CONNECTIONS = 4;
+export class ActorCluster extends Context.Service()("@rikalabs/akter/testing/cluster/ActorCluster") {
+}
+const key = (address) => `${address.host}:${address.port}`;
+const unreachable = (address) => Socket.SocketError.make({
+    reason: Socket.SocketOpenError.make({
+        kind: "Unknown",
+        cause: new Error(`Runner ${key(address)} is unreachable`),
+    }),
+});
+/**
+ * Runner-to-runner connections inside one process. Every frame is encoded and
+ * decoded as it would be on a socket, and a killed runner's connections fail
+ * mid-stream.
+ */
+const makeNetwork = Effect.sync(() => {
+    const listeners = new Map();
+    const links = new Map();
+    const pipe = (sever) => {
+        let controller;
+        const stream = new TransformStream({
+            start: (started) => {
+                controller = started;
+            },
+        });
+        sever.add(() => controller?.error(new Error("Runner killed")));
+        return stream;
+    };
+    const dial = (address) => Effect.suspend(() => {
+        const accept = listeners.get(key(address));
+        const sever = links.get(key(address));
+        if (accept === undefined || sever === undefined)
+            return Effect.fail(unreachable(address));
+        const up = pipe(sever);
+        const down = pipe(sever);
+        return Socket.fromTransformStream(Effect.succeed({ readable: up.readable, writable: down.writable })).pipe(Effect.flatMap((socket) => Queue.offer(accept, socket)), Effect.as({ readable: down.readable, writable: up.writable }));
+    });
+    const listen = (address) => Effect.acquireRelease(Effect.gen(function* () {
+        const accept = yield* Queue.unbounded();
+        listeners.set(key(address), accept);
+        links.set(key(address), new Set());
+        return SocketServer.SocketServer.of({
+            address: NetAddress.inetAddressFromIpStringUnsafe("127.0.0.1", address.port),
+            run: (handler) => Queue.take(accept).pipe(Effect.flatMap((socket) => Effect.forkChild(handler(socket))), Effect.forever),
+        });
+    }), () => Effect.sync(() => close(address)));
+    const close = (address) => {
+        listeners.delete(key(address));
+        for (const sever of links.get(key(address)) ?? [])
+            sever();
+        links.delete(key(address));
+    };
+    const serialization = RpcSerialization.ndjson;
+    const clients = Runners.RpcClientProtocol.of({
+        codecFor: serialization.codecFor,
+        make: (address) => Socket.fromTransformStream(dial(address)).pipe(Effect.flatMap((socket) => RpcClient.makeProtocolSocket().pipe(Effect.provideService(Socket.Socket, socket))), Effect.provideService(RpcSerialization.RpcSerialization, serialization)),
+    });
+    const runner = (address) => RunnerServer.layer.pipe(Layer.provideMerge(admissionSharding), Layer.provideMerge(Runners.layerRpc), Layer.provide(RpcServer.layerProtocolSocketServer), Layer.provide(Layer.effect(SocketServer.SocketServer, listen(address))), Layer.provide(Layer.succeed(Runners.RpcClientProtocol, clients)), Layer.provide(Layer.succeed(RpcSerialization.RpcSerialization, serialization)));
+    return { runner, close };
+});
+/**
+ * Provides an `ActorCluster` of `options.runners` real runners sharing one Postgres database, each serving runner RPCs on its own listener.
+ * The first runner migrates the database and the rest start together. Runner rows carry the cluster's tenant, so rows another cluster left in the same database are never mistaken for this one's.
+ * `kill` cuts a runner's database and runner connections at once so Postgres rolls back its open turns; a graceful exit closes its layer first so it releases its locks.
+ * Fails to build when `database` is missing or is not a Postgres URL, since PGlite has a single connection.
+ */
+export const clusterLayer = (options) => Layer.effect(ActorCluster, Effect.gen(function* () {
+    const { database } = options;
+    if (database === undefined || !Redacted.isRedacted(database))
+        return yield* Effect.die(new Error("ActorTest.cluster needs a Postgres database URL; PGlite has a single connection, so it cannot host several runners"));
+    if (!Number.isInteger(options.runners) || options.runners < 1)
+        return yield* Effect.die(new Error("ActorTest.cluster needs at least one runner"));
+    if (Array.from({ length: options.runners }).every((_, index) => (options.holdersOnly ?? []).includes(index)))
+        return yield* Effect.die(new Error("ActorTest.cluster needs a runner that hosts actors"));
+    const expiration = Duration.fromInputUnsafe(options.shardLockExpiration);
+    const expirationSeconds = Math.ceil(Duration.toSeconds(expiration));
+    const crypto = yield* Crypto.Crypto;
+    const tenant = yield* crypto.randomUUIDv4.pipe(Effect.orDie);
+    const network = yield* makeNetwork;
+    const services = yield* Effect.context();
+    const sql = Context.get(yield* Layer.build(Database.postgres({ url: database, maxConnections: 2 })).pipe(Effect.orDie), SqlClient.SqlClient);
+    const host = `runner-${tenant}`;
+    let incarnation = 0;
+    const runners = [];
+    const addresses = new Map();
+    const stopping = [];
+    const url = new URL(Redacted.value(database));
+    let holding = false;
+    const failover = Effect.sync(() => {
+        holding = false;
+        for (const runner of runners)
+            for (const socket of runner.sockets ?? [])
+                socket.destroy();
+    });
+    const hostsActors = (runner) => !(options.holdersOnly ?? []).includes(runners.indexOf(runner));
+    /**
+     * Bound to one incarnation's socket set, so a killed process that is
+     * still winding down cannot reach the database again once its runner
+     * has started as a new process.
+     */
+    const dial = (runner, incarnationSockets) => () => {
+        const sockets = runner.sockets === incarnationSockets ? incarnationSockets : undefined;
+        if (sockets === undefined) {
+            const refused = new NetSocket();
+            queueMicrotask(() => refused.destroy(new Error("Runner killed")));
+            return refused;
+        }
+        const socket = connect({
+            host: url.hostname,
+            port: Number(url.port || 5432),
+            noDelay: true,
+        });
+        sockets.add(socket);
+        socket.once("close", () => sockets.delete(socket));
+        if (holding)
+            socket.pause();
+        return socket;
+    };
+    /**
+     * A killed process that is still winding down stays killed when its
+     * runner starts again under a new address.
+     */
+    const storage = (runner, mine) => (inner) => {
+        const state = () => runner.address === mine ? runner.heartbeat : "killed";
+        return {
+            ...inner,
+            getRunners: Effect.suspend(() => state() === "running" || runner.runners === undefined
+                ? inner.getRunners.pipe(Effect.tap((seen) => Effect.sync(() => {
+                    runner.runners = seen;
+                })))
+                : Effect.succeed([...runner.runners])),
+            refresh: (address, shardIds) => Effect.suspend(() => {
+                if (state() === "running")
+                    return inner.refresh(address, shardIds);
+                return Effect.succeed(state() === "paused" ? Array.from(shardIds) : []);
+            }),
+            acquire: (address, shardIds) => Effect.suspend(() => state() === "running" ? inner.acquire(address, shardIds) : Effect.succeed([])),
+            release: (address, shardId) => Effect.suspend(() => state() === "running" ? inner.release(address, shardId) : Effect.void),
+            releaseAll: (address) => Effect.suspend(() => state() === "running" ? inner.releaseAll(address) : Effect.void),
+            unregister: (address) => Effect.suspend(() => state() === "running" ? inner.unregister(address) : Effect.void),
+            setRunnerHealth: (address, healthy) => Effect.suspend(() => state() === "running" ? inner.setRunnerHealth(address, healthy) : Effect.void),
+        };
+    };
+    const start = Effect.fnUntraced(function* (runner) {
+        incarnation += 1;
+        runner.address = RunnerAddress.RunnerAddress.make({ host, port: incarnation });
+        runner.heartbeat = "running";
+        runner.runners = undefined;
+        const sockets = new Set();
+        runner.sockets = sockets;
+        addresses.set(key(runner.address), runners.indexOf(runner));
+        const scope = yield* Scope.make();
+        runner.scope = scope;
+        const layer = Layer.merge(options.actors, options.runnerActors?.(runners.indexOf(runner)) ?? Layer.empty).pipe(Layer.provideMerge(ActorTest.layer({
+            ...options,
+            maxConnections: options.maxConnections ?? RUNNER_CONNECTIONS,
+        }).pipe(Layer.provide([
+            Layer.succeed(ClusterMember, { tenant, connect: dial(runner, sockets) }),
+            Layer.succeed(RunnerWiring, {
+                config: {
+                    ...TIMINGS,
+                    runnerAddress: Option.some(runner.address),
+                    shardsPerGroup: SHARDS,
+                    assignedShardGroups: hostsActors(runner) ? ["default"] : [],
+                    shardLockExpiration: expiration,
+                    shardLockDisableAdvisory: true,
+                },
+                sharding: network.runner(runner.address),
+                storage: storage(runner, runner.address),
+            }),
+        ]))));
+        runner.context = yield* Layer.buildWithMemoMap(layer, yield* Layer.makeMemoMap, scope).pipe(Effect.provideContext(services), Effect.orDie, Effect.onError(() => Scope.close(scope, Exit.void)));
+    });
+    const stop = Effect.fnUntraced(function* (runner) {
+        const { scope, sockets } = runner;
+        runner.heartbeat = "killed";
+        runner.scope = undefined;
+        runner.context = undefined;
+        runner.sockets = undefined;
+        network.close(runner.address);
+        for (const socket of sockets ?? [])
+            socket.destroy();
+        if (scope !== undefined)
+            stopping.push(yield* Effect.forkDetach(Scope.close(scope, Exit.void)));
+    });
+    const shutdown = Effect.fnUntraced(function* (runner) {
+        const scope = runner.scope;
+        runner.scope = undefined;
+        runner.context = undefined;
+        if (scope !== undefined)
+            yield* Scope.close(scope, Exit.void);
+        yield* stop(runner);
+    });
+    const at = (index) => Effect.suspend(() => {
+        const runner = runners[index];
+        return runner === undefined
+            ? Effect.die(new Error(`No runner ${index}; the cluster has ${runners.length}`))
+            : Effect.succeed(runner);
+    });
+    const live = (index) => at(index).pipe(Effect.flatMap((runner) => runner.context === undefined
+        ? Effect.die(new Error(`Runner ${index} is stopped`))
+        : Effect.succeed(runner.context)));
+    const locks = sql `
+        SELECT shard_id, address FROM cluster_locks
+        WHERE acquired_at >= NOW() - ${`${expirationSeconds} seconds`}::interval
+          AND address LIKE ${`${host}:%`}`.pipe(Effect.orDie);
+    const ready = Effect.gen(function* () {
+        const serving = runners.filter((runner) => runner.heartbeat === "running" && hostsActors(runner));
+        if (serving.length === 0)
+            return true;
+        const ring = HashRing.make();
+        for (const runner of serving)
+            HashRing.add(ring, runner.address, { weight: 1 });
+        const expected = HashRing.getShards(ring, SHARDS);
+        const held = new Map((yield* locks).map((lock) => [lock.shard_id, lock.address]));
+        return expected.every((address, index) => held.get(`default:${index + 1}`) === key(address));
+    }).pipe(Effect.repeat({ schedule: Schedule.spaced("50 millis"), until: (settled) => settled }), Effect.timeoutOrElse({
+        duration: "60 seconds",
+        orElse: () => Effect.die(new Error("Cluster runners did not settle their shards")),
+    }), Effect.asVoid);
+    yield* Effect.addFinalizer(() => Effect.forEach(runners, stop, { discard: true }).pipe(Effect.andThen(Fiber.awaitAll(stopping)), Effect.timeoutOrElse({
+        duration: "15 seconds",
+        orElse: () => Effect.die(new Error("Killed cluster runners did not wind down")),
+    })));
+    for (let index = 0; index < options.runners; index++)
+        runners.push({
+            address: RunnerAddress.RunnerAddress.make({ host: "runner", port: 0 }),
+            sockets: undefined,
+            scope: undefined,
+            context: undefined,
+            heartbeat: "killed",
+            runners: undefined,
+        });
+    yield* start(runners[0]);
+    yield* Effect.forEach(runners.slice(1), start, { concurrency: "unbounded", discard: true });
+    yield* ready;
+    return ActorCluster.of({
+        runners: options.runners,
+        tenant,
+        sql,
+        on: (index) => (effect) => live(index).pipe(Effect.flatMap((context) => Effect.provideContext(effect, context))),
+        holdReplies: Effect.sync(() => {
+            holding = true;
+            for (const runner of runners)
+                for (const socket of runner.sockets ?? [])
+                    socket.pause();
+        }),
+        failover,
+        kill: (index) => at(index).pipe(Effect.flatMap(stop)),
+        shutdown: (index) => at(index).pipe(Effect.flatMap(shutdown)),
+        restart: (index) => at(index).pipe(Effect.tap((runner) => (runner.scope === undefined ? Effect.void : stop(runner))), Effect.flatMap(start)),
+        pauseHeartbeat: (index) => at(index).pipe(Effect.flatMap((runner) => runner.heartbeat === "running"
+            ? Effect.sync(() => {
+                const paused = runner.address;
+                runner.heartbeat = "paused";
+                return {
+                    resume: Effect.sync(() => {
+                        if (runner.heartbeat === "paused" && runner.address === paused)
+                            runner.heartbeat = "running";
+                    }),
+                };
+            })
+            : Effect.die(new Error(`Runner ${index} is not running`)))),
+        owner: Effect.fnUntraced(function* (ref) {
+            const serving = runners.find((runner) => runner.context !== undefined);
+            if (serving === undefined)
+                return undefined;
+            const shard = yield* Context.get(serving.context, InternalActors).shardId(ref);
+            const holder = (yield* locks).find((lock) => lock.shard_id === shard);
+            return holder === undefined ? undefined : addresses.get(holder.address);
+        }),
+        ready,
+    });
+}));

package/dist/testing/conformance/access.d.ts

@@ -0,0 +1,5 @@
+import type { ConformanceCase, ConformanceSuite } from "../conformance.ts";
+/** Cases for the default caller and tenant, actor `access` policies, and the global `authorize` hook they combine with. */
+export declare const accessConformance: ReadonlyArray<ConformanceCase>;
+/** Access cases call the served HTTP actors. */
+export declare const accessSuite: ConformanceSuite;