ignotum 0.0.0 → 0.0.2

package/src/dev-runtime/sync.ts

@@ -0,0 +1,473 @@
+// @effect-diagnostics-next-line nodeBuiltinImport:off Vite exposes its HTTP server through Node's adapter types.
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import { NodeHttpServer, NodeServices, NodeSocket } from "@effect/platform-node";
+import { SqliteClient } from "@effect/sql-sqlite-node";
+import {
+  ClientMessageJson,
+  ServerMessageJson,
+  type ClientMessage,
+  type FunctionAddress,
+  type Operation,
+  type ProtocolErrorCode,
+  type ServerMessage,
+  type SubscriptionId,
+  type WireResult,
+} from "@ignotum/contracts/runtime/sync";
+import {
+  Effect,
+  Context,
+  FileSystem,
+  Function,
+  FiberSet,
+  HashMap,
+  Layer,
+  ManagedRuntime,
+  Option,
+  Path,
+  PartitionedSemaphore,
+  PubSub,
+  Ref,
+  Schema,
+  Semaphore,
+} from "effect";
+import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import type * as Socket from "effect/unstable/socket/Socket";
+import type { Plugin, ViteDevServer } from "vite";
+import { FunctionRuntime, type PreparedFunction } from "@ignotum/runtime/functions";
+import { QueryInvalidation } from "@ignotum/runtime/sync";
+
+import { generate } from "../cli/codegen.js";
+import { isIgnotumPath, syncPath } from "../internal/http-paths.js";
+import { LocalDatabase } from "./database.js";
+import { idGeneratorLayer } from "./id.js";
+import { FunctionExecutor, FunctionRegistry, functionRuntimeLayer } from "./functions.js";
+
+interface QuerySubscription {
+  readonly args: Schema.Json;
+  readonly function: FunctionAddress;
+}
+
+export { QueryInvalidation };
+
+export const queryInvalidationLayer = Layer.effect(
+  QueryInvalidation,
+  Effect.gen(function* () {
+    const pubsub = yield* PubSub.unbounded<void>();
+    return QueryInvalidation.of({
+      publish: PubSub.publish(pubsub, undefined),
+      subscribe: PubSub.subscribe(pubsub),
+    });
+  }),
+);
+
+const operationForQuery = (subscriptionId: SubscriptionId): Operation => ({
+  type: "Query",
+  id: subscriptionId,
+});
+
+const protocolError = (
+  code: ProtocolErrorCode,
+  message: string,
+  operation?: Operation,
+): ServerMessage => {
+  if (operation === undefined) {
+    return { type: "ProtocolError", code, message };
+  }
+  return { type: "ProtocolError", code, message, operation };
+};
+
+export const runSession = Effect.fn("SyncServer.runSession")(function* (socket: Socket.Socket) {
+  const runtime = yield* FunctionRuntime;
+  const invalidation = yield* QueryInvalidation;
+  const subscriptions = yield* Ref.make(HashMap.empty<SubscriptionId, QuerySubscription>());
+  const invocationFibers = yield* FiberSet.make();
+  const querySemaphore = yield* PartitionedSemaphore.make<SubscriptionId>({ permits: 1 });
+  const messageSemaphore = yield* Semaphore.make(1);
+  const writeSemaphore = yield* Semaphore.make(1);
+  const write = yield* socket.writer;
+
+  const send = Effect.fn("SyncServer.send")(function* (message: ServerMessage) {
+    yield* writeSemaphore.withPermits(1)(
+      Schema.encodeEffect(ServerMessageJson)(message).pipe(Effect.flatMap(write)),
+    );
+  });
+
+  const sendResolutionError = (
+    operation: Operation,
+    error:
+      | { readonly _tag: "UnknownFunction"; readonly message: string }
+      | { readonly _tag: "WrongFunctionKind"; readonly message: string }
+      | { readonly _tag: "InvalidArguments"; readonly message: string }
+      | { readonly _tag: "FunctionUnavailable"; readonly message: string },
+    deliver: (
+      message: ServerMessage,
+    ) => Effect.Effect<void, Schema.SchemaError | Socket.SocketError> = send,
+  ) => {
+    const code: ProtocolErrorCode = error._tag;
+    return deliver(protocolError(code, error.message, operation));
+  };
+
+  const isActive = (subscriptionId: SubscriptionId, subscription: QuerySubscription) =>
+    Ref.get(subscriptions).pipe(
+      Effect.map(
+        (current) => Option.getOrUndefined(HashMap.get(current, subscriptionId)) === subscription,
+      ),
+    );
+
+  const sendIfActive = Effect.fn("SyncServer.sendIfActive")(function* (
+    subscriptionId: SubscriptionId,
+    subscription: QuerySubscription,
+    message: ServerMessage,
+  ) {
+    if (yield* isActive(subscriptionId, subscription)) {
+      yield* send(message);
+    }
+  });
+
+  const executeQuery = Effect.fn("SyncServer.executeQuery")(function* (
+    subscriptionId: SubscriptionId,
+    subscription: QuerySubscription,
+    previouslyPrepared?: PreparedFunction,
+  ) {
+    if (!(yield* isActive(subscriptionId, subscription))) return;
+
+    const operation = operationForQuery(subscriptionId);
+    const deliver = (message: ServerMessage) => sendIfActive(subscriptionId, subscription, message);
+    const prepared =
+      previouslyPrepared ??
+      (yield* runtime.prepare(subscription.function, "Query", subscription.args).pipe(
+        Effect.catchTags({
+          FunctionUnavailable: (error) => sendResolutionError(operation, error, deliver),
+          InvalidArguments: (error) => sendResolutionError(operation, error, deliver),
+          UnknownFunction: (error) => sendResolutionError(operation, error, deliver),
+          WrongFunctionKind: (error) => sendResolutionError(operation, error, deliver),
+        }),
+      ));
+    if (prepared === undefined) return;
+
+    const result = yield* prepared.execute;
+    yield* deliver({
+      type: "QuerySnapshot",
+      id: subscriptionId,
+      result,
+    });
+  });
+
+  const scheduleQuery = (
+    subscriptionId: SubscriptionId,
+    subscription: QuerySubscription,
+    previouslyPrepared?: PreparedFunction,
+  ) =>
+    querySemaphore
+      .withPermits(
+        subscriptionId,
+        1,
+      )(executeQuery(subscriptionId, subscription, previouslyPrepared))
+      .pipe(
+        Effect.catchCause((cause) =>
+          Effect.logError("A query refresh fiber failed.").pipe(
+            Effect.annotateLogs({ cause, function: subscription.function, subscriptionId }),
+          ),
+        ),
+        FiberSet.run(invocationFibers),
+        Effect.asVoid,
+      );
+
+  const refresh = Effect.fn("SyncServer.refresh")(function* () {
+    const current = yield* Ref.get(subscriptions);
+    yield* Effect.forEach(HashMap.toEntries(current), ([subscriptionId, subscription]) =>
+      scheduleQuery(subscriptionId, subscription),
+    );
+  });
+
+  const invalidations = yield* invalidation.subscribe;
+  yield* PubSub.take(invalidations).pipe(
+    Effect.flatMap(refresh),
+    Effect.forever,
+    Effect.forkScoped,
+  );
+
+  const handleSubscribe = Effect.fn("SyncServer.handleSubscribe")(function* (
+    message: Extract<ClientMessage, { readonly type: "Subscribe" }>,
+  ) {
+    const operation = operationForQuery(message.id);
+    const current = yield* Ref.get(subscriptions);
+
+    if (HashMap.has(current, message.id)) {
+      yield* send(
+        protocolError(
+          "DuplicateOperationId",
+          `Subscription ${message.id} already exists.`,
+          operation,
+        ),
+      );
+      return;
+    }
+
+    const prepared = yield* runtime.prepare(message.function, "Query", message.args).pipe(
+      Effect.catchTags({
+        FunctionUnavailable: (error) => sendResolutionError(operation, error),
+        InvalidArguments: (error) => sendResolutionError(operation, error),
+        UnknownFunction: (error) => sendResolutionError(operation, error),
+        WrongFunctionKind: (error) => sendResolutionError(operation, error),
+      }),
+    );
+
+    if (prepared === undefined) {
+      return;
+    }
+
+    const subscription = { args: message.args, function: message.function };
+    yield* Ref.update(subscriptions, HashMap.set(message.id, subscription));
+    yield* scheduleQuery(message.id, subscription, prepared);
+  });
+
+  const handleMutate = Effect.fn("SyncServer.handleMutate")(function* (
+    message: Extract<ClientMessage, { readonly type: "Mutate" }>,
+  ) {
+    const operation: Operation = { type: "Mutate", id: message.id };
+    const prepared = yield* runtime.prepare(message.function, "Mutation", message.args).pipe(
+      Effect.catchTags({
+        FunctionUnavailable: (error) => sendResolutionError(operation, error),
+        InvalidArguments: (error) => sendResolutionError(operation, error),
+        UnknownFunction: (error) => sendResolutionError(operation, error),
+        WrongFunctionKind: (error) => sendResolutionError(operation, error),
+      }),
+    );
+
+    if (prepared === undefined) {
+      return;
+    }
+
+    yield* prepared.execute.pipe(
+      Effect.flatMap((result: WireResult) => {
+        const response = send({ type: "MutationResult", id: message.id, result });
+        return result.type === "Success"
+          ? response.pipe(Effect.ensuring(invalidation.publish))
+          : response;
+      }),
+      Effect.catchCause((cause) =>
+        Effect.logError("A mutation invocation fiber failed.").pipe(
+          Effect.annotateLogs({ cause, function: message.function, requestId: message.id }),
+        ),
+      ),
+      FiberSet.run(invocationFibers),
+      Effect.asVoid,
+    );
+  });
+
+  const handleMessage = Effect.fn("SyncServer.handleMessage")(function* (text: string) {
+    const message = yield* Schema.decodeEffect(ClientMessageJson)(text).pipe(
+      Effect.catch(() =>
+        send(protocolError("InvalidMessage", "The WebSocket frame is not valid Ignotum JSON.")),
+      ),
+    );
+
+    if (message === undefined) {
+      return;
+    }
+
+    switch (message.type) {
+      case "Subscribe":
+        yield* handleSubscribe(message);
+        return;
+      case "Unsubscribe":
+        yield* Ref.update(subscriptions, HashMap.remove(message.id));
+        return;
+      case "Mutate":
+        yield* handleMutate(message);
+        return;
+    }
+  });
+
+  yield* socket.runString((text) => messageSemaphore.withPermits(1)(handleMessage(text)));
+});
+
+interface SyncHandlersService {
+  readonly http: (request: IncomingMessage, response: ServerResponse) => void;
+  readonly upgrade: NodeJS.EventEmitter extends infer _EventEmitter
+    ? (request: IncomingMessage, socket: import("node:stream").Duplex, head: Buffer) => void
+    : never;
+  readonly reload: (file: string, event: "add" | "change" | "unlink") => Effect.Effect<void>;
+}
+
+class SyncHandlers extends Context.Service<SyncHandlers, SyncHandlersService>()(
+  "ignotum/dev-runtime/sync/SyncHandlers",
+) {}
+
+const makeHandlersLayer = (
+  server: ViteDevServer,
+  projectDirectory: string,
+  databasePath: string,
+) => {
+  const databaseLayer = LocalDatabase.layer.pipe(
+    Layer.provide(Layer.merge(idGeneratorLayer, SqliteClient.layer({ filename: databasePath }))),
+  );
+  const executorLayer = FunctionExecutor.layer.pipe(Layer.provide(databaseLayer));
+  const devFunctionRuntimeLayer = functionRuntimeLayer.pipe(
+    Layer.provide(
+      Layer.merge(
+        FunctionRegistry.layer(server, projectDirectory).pipe(Layer.provide(NodeServices.layer)),
+        executorLayer,
+      ),
+    ),
+  );
+  const dependencies = Layer.mergeAll(
+    devFunctionRuntimeLayer,
+    queryInvalidationLayer,
+    NodeServices.layer,
+  );
+
+  return Layer.effect(
+    SyncHandlers,
+    Effect.gen(function* () {
+      const invalidation = yield* QueryInvalidation;
+      const fileSystem = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      const scope = yield* Effect.scope;
+      const reloadSemaphore = yield* Semaphore.make(1);
+      const webSocketServer = yield* Effect.acquireRelease(
+        Effect.sync(
+          () => new NodeSocket.NodeWS.WebSocketServer({ maxPayload: 1024 * 1024, noServer: true }),
+        ),
+        (instance) =>
+          Effect.callback<void>((resume) => {
+            instance.close(() => resume(Effect.void));
+          }),
+      );
+      const httpApp = Effect.gen(function* () {
+        const request = yield* HttpServerRequest.HttpServerRequest;
+        const pathname = new URL(request.url, "http://ignotum.local").pathname;
+        return yield* HttpServerResponse.json(
+          pathname === syncPath
+            ? { code: "UpgradeRequired", message: `Connect to ${syncPath} with WebSocket.` }
+            : { code: "NotFound", message: "Unknown Ignotum API route." },
+          { status: pathname === syncPath ? 426 : 404 },
+        );
+      });
+      const socketApp = Effect.gen(function* () {
+        const request = yield* HttpServerRequest.HttpServerRequest;
+        const socket = yield* request.upgrade;
+        yield* runSession(socket);
+        return HttpServerResponse.empty();
+      });
+      const http = yield* NodeHttpServer.makeHandler(httpApp, { scope });
+      const upgrade = yield* NodeHttpServer.makeUpgradeHandler(
+        Effect.succeed(webSocketServer),
+        socketApp,
+        { scope },
+      );
+      const serverDirectory = path.join(projectDirectory, "server");
+      const reloadUnsafe = Effect.fn("SyncServer.reload")(function* (
+        file: string,
+        event: "add" | "change" | "unlink",
+      ) {
+        const relative = path.relative(serverDirectory, file);
+        if (relative.startsWith("..") || path.isAbsolute(relative) || !file.endsWith(".ts")) {
+          return;
+        }
+
+        if (event !== "change") {
+          yield* generate(projectDirectory).pipe(
+            Effect.provideService(FileSystem.FileSystem, fileSystem),
+            Effect.provideService(Path.Path, path),
+          );
+        }
+        yield* invalidation.publish;
+      });
+      const reload = (file: string, event: "add" | "change" | "unlink") =>
+        reloadSemaphore
+          .withPermits(1)(reloadUnsafe(file, event))
+          .pipe(
+            Effect.catchCause((cause) =>
+              Effect.logError("Could not reload Ignotum server functions.").pipe(
+                Effect.annotateLogs({ cause, event, file }),
+              ),
+            ),
+          );
+
+      return SyncHandlers.of({ http, reload, upgrade });
+    }),
+  ).pipe(Layer.provide(dependencies));
+};
+
+const isApiPath = (request: IncomingMessage): boolean => {
+  const pathname = new URL(request.url ?? "/", "http://ignotum.local").pathname;
+  return isIgnotumPath(pathname);
+};
+
+const isAppOrigin = (host: string | undefined, origin: string | undefined): boolean => {
+  if (host === undefined || origin === undefined) return false;
+
+  return Option.match(Schema.decodeOption(Schema.URLFromString)(origin), {
+    onNone: () => false,
+    onSome: (url) => url.origin === origin && url.host === host,
+  });
+};
+
+const rejectUpgrade = (socket: import("node:stream").Duplex): void => {
+  socket.write("HTTP/1.1 403 Forbidden\r\nConnection: close\r\nContent-Length: 0\r\n\r\n", () =>
+    socket.destroy(),
+  );
+};
+
+export const syncPluginInternals = { isAppOrigin };
+
+export const ignotumSyncPlugin: {
+  (databasePath: string): (projectDirectory: string) => Plugin;
+  (projectDirectory: string, databasePath: string): Plugin;
+} = Function.dual(2, (projectDirectory: string, databasePath: string): Plugin => ({
+  name: "ignotum:sync",
+  configureServer: (server) => {
+    if (server.httpServer === null) {
+      throw new Error("Ignotum sync requires Vite's Node HTTP server.");
+    }
+
+    const runtime = ManagedRuntime.make(makeHandlersLayer(server, projectDirectory, databasePath));
+    const httpServer = server.httpServer;
+    return runtime.runPromise(SyncHandlers).then(
+      (handlers) => {
+        const onUpgrade = (
+          request: IncomingMessage,
+          socket: import("node:stream").Duplex,
+          head: Buffer,
+        ) => {
+          if (new URL(request.url ?? "/", "http://ignotum.local").pathname !== syncPath) return;
+          if (!isAppOrigin(request.headers.host, request.headers.origin)) {
+            rejectUpgrade(socket);
+            return;
+          }
+          handlers.upgrade(request, socket, head);
+        };
+        const onAdd = (file: string) => runtime.runFork(handlers.reload(file, "add"));
+        const onChange = (file: string) => runtime.runFork(handlers.reload(file, "change"));
+        const onUnlink = (file: string) => runtime.runFork(handlers.reload(file, "unlink"));
+        const cleanup = () => {
+          httpServer.off("upgrade", onUpgrade);
+          server.watcher.off("add", onAdd);
+          server.watcher.off("change", onChange);
+          server.watcher.off("unlink", onUnlink);
+          void runtime.dispose();
+        };
+
+        httpServer.on("upgrade", onUpgrade);
+        httpServer.once("close", cleanup);
+        server.watcher.on("add", onAdd);
+        server.watcher.on("change", onChange);
+        server.watcher.on("unlink", onUnlink);
+        server.middlewares.use((request, response, next) => {
+          if (!isApiPath(request)) {
+            next();
+            return;
+          }
+          handlers.http(request, response);
+        });
+      },
+      (error) => {
+        void runtime.dispose();
+        throw error;
+      },
+    );
+  },
+}));

package/src/internal/api.ts

@@ -0,0 +1,141 @@
+import { Predicate } from "effect";
+import type { Effect } from "effect";
+
+import type { ErrorValue, InternalServerError } from "@ignotum/contracts/runtime/result";
+import { FunctionAddress } from "@ignotum/contracts/runtime/sync";
+
+const FunctionReferenceTypeId: unique symbol = Symbol.for("ignotum/internal/api/FunctionReference");
+declare const FunctionReferenceTypesTypeId: unique symbol;
+
+type FunctionKind = "Mutation" | "Query";
+
+export interface FunctionReference<
+  Kind extends FunctionKind,
+  Args,
+  Success,
+  Failure extends ErrorValue,
+> {
+  readonly [FunctionReferenceTypeId]: FunctionAddress;
+  readonly [FunctionReferenceTypesTypeId]?: {
+    readonly kind: Kind;
+    readonly args: Args;
+    readonly value: Success;
+    readonly error: Failure;
+  };
+}
+
+type ReferenceTypes<Reference> = Reference extends {
+  readonly [FunctionReferenceTypesTypeId]?: infer Types;
+}
+  ? Exclude<Types, undefined>
+  : never;
+
+export declare namespace FunctionReference {
+  type Args<Reference> =
+    ReferenceTypes<Reference> extends { readonly args: infer Args } ? Args : never;
+  type Failure<Reference> =
+    ReferenceTypes<Reference> extends {
+      readonly error: infer Failure;
+    }
+      ? Failure
+      : never;
+  type Kind<Reference> =
+    ReferenceTypes<Reference> extends { readonly kind: infer Kind } ? Kind : never;
+  type Success<Reference> =
+    ReferenceTypes<Reference> extends {
+      readonly value: infer Success;
+    }
+      ? Success
+      : never;
+}
+
+type ReferenceOf<Definition> = Definition extends {
+  readonly _tag: infer Kind extends FunctionKind;
+  readonly handler: (
+    ...arguments_: infer HandlerArguments
+  ) => Generator<infer Yielded, infer Success, never>;
+}
+  ? HandlerArguments extends readonly [infer _Context, ...infer Rest]
+    ? FunctionReference<
+        Kind,
+        Rest extends readonly [infer Args, ...ReadonlyArray<unknown>] ? Args : void,
+        Success,
+        | (Yielded extends Effect.Effect<unknown, infer Failure extends ErrorValue, never>
+            ? Failure
+            : never)
+        | InternalServerError
+      >
+    : never
+  : never;
+
+type ApiModule<Module> = {
+  readonly [FunctionName in keyof Module as FunctionName extends string
+    ? ReferenceOf<Module[FunctionName]> extends never
+      ? never
+      : FunctionName
+    : never]: ReferenceOf<Module[FunctionName]>;
+};
+
+export type Api<Modules> = {
+  readonly [ModuleName in keyof Modules]: ApiModule<Modules[ModuleName]>;
+};
+
+export const functionPathOf = <
+  Kind extends FunctionKind,
+  Args,
+  Success,
+  Failure extends ErrorValue,
+>(
+  reference: FunctionReference<Kind, Args, Success, Failure>,
+) => reference[FunctionReferenceTypeId];
+
+const makeModuleReference = (moduleName: string) => {
+  const references = new Map<string, object>();
+
+  return new Proxy(
+    {},
+    {
+      get: (_target, functionName) => {
+        if (!Predicate.isString(functionName)) {
+          return undefined;
+        }
+
+        const existing = references.get(functionName);
+        if (existing !== undefined) {
+          return existing;
+        }
+
+        const reference = {
+          [FunctionReferenceTypeId]: FunctionAddress.make(`api.${moduleName}.${functionName}`),
+        };
+        references.set(functionName, reference);
+        return reference;
+      },
+    },
+  );
+};
+
+export function createApi<Modules>(): Api<Modules>;
+export function createApi() {
+  const modules = new Map<string, object>();
+
+  return new Proxy(
+    {},
+    {
+      get: (_target, moduleName) => {
+        if (!Predicate.isString(moduleName)) {
+          return undefined;
+        }
+
+        const existing = modules.get(moduleName);
+        if (existing !== undefined) {
+          return existing;
+        }
+
+        const moduleReference = makeModuleReference(moduleName);
+        modules.set(moduleName, moduleReference);
+        return moduleReference;
+      },
+    },
+  );
+}

package/src/internal/http-paths.ts

@@ -0,0 +1,5 @@
+export const ignotumPathPrefix = "/_ignotum";
+export const syncPath = `${ignotumPathPrefix}/sync`;
+
+export const isIgnotumPath = (pathname: string): boolean =>
+  pathname === ignotumPathPrefix || pathname.startsWith(`${ignotumPathPrefix}/`);

package/src/internal/server.ts

@@ -0,0 +1,3 @@
+import { bindSchema as bindContractSchema } from "@ignotum/contracts/schema";
+
+export const bindSchema: typeof bindContractSchema = bindContractSchema;

package/src/internal/types.ts

@@ -0,0 +1,2 @@
+export { SchemaDefinitionTypeId } from "@ignotum/contracts/schema";
+export type { Document, Id, SchemaDefinitionOf } from "@ignotum/contracts/schema";

package/src/raw.d.ts

@@ -0,0 +1,4 @@
+declare module "*?raw" {
+  const content: string;
+  export default content;
+}

package/src/server/index.ts

@@ -0,0 +1,8 @@
+import { Result as contractResult } from "@ignotum/contracts/runtime/result";
+import type { ErrorValue, Result as ContractResult } from "@ignotum/contracts/runtime/result";
+import { defineSchema as defineContractSchema } from "@ignotum/contracts/schema";
+
+export const Result: typeof contractResult = contractResult;
+export type Result<Success, Failure extends ErrorValue> = ContractResult<Success, Failure>;
+export const defineSchema: typeof defineContractSchema = defineContractSchema;
+export type { DefinedSchema, SchemaAuthoring } from "@ignotum/contracts/schema";