terrascale 0.3.0

package/src/local/context.js

@@ -0,0 +1,23 @@
+/** @typedef {"permissive" | "required"} LocalAuthenticationMode */
+/**
+ * @param {unknown} value
+ * @param {number} [status]
+ * @returns {Response}
+ */
+export function jsonResponse(value, status = 200) {
+  const body = JSON.stringify(value);
+  if (new TextEncoder().encode(body).byteLength > 4 * 1024 * 1024)
+    return problemResponse(503, "capacity");
+  return new Response(body, {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+/**
+ * @param {number} status
+ * @param {string} code
+ * @returns {Response}
+ */
+export function problemResponse(status, code) {
+  return jsonResponse({ error: { code } }, status);
+}

package/src/local/environment.js

@@ -0,0 +1,109 @@
+export const localSqlitePresenceIndicators = /** @type {const} */ ([
+  "CI",
+  "CONTINUOUS_INTEGRATION",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "FORGEJO_ACTIONS",
+  "GITEA_ACTIONS",
+  "TF_BUILD",
+  "BUILDKITE",
+  "CIRCLECI",
+  "JENKINS_URL",
+  "TEAMCITY_VERSION",
+  "VERCEL",
+  "NETLIFY",
+  "CF_PAGES",
+  "RENDER",
+  "FLY_APP_NAME",
+  "K_SERVICE",
+  "CLOUD_RUN_JOB",
+  "KUBERNETES_SERVICE_HOST",
+  "AWS_LAMBDA_FUNCTION_NAME",
+  "AWS_EXECUTION_ENV",
+  "ECS_CONTAINER_METADATA_URI",
+  "ECS_CONTAINER_METADATA_URI_V4",
+  "WEBSITE_INSTANCE_ID",
+  "WEBSITE_SITE_NAME",
+  "FUNCTIONS_WORKER_RUNTIME",
+  "DYNO",
+  "HEROKU_APP_NAME",
+  "RAILWAY_ENVIRONMENT",
+  "RAILWAY_SERVICE_ID",
+  "NOMAD_ALLOC_ID",
+  "TERRASCALE_DEPLOYMENT",
+  "TERRASCALE_QUALIFICATION",
+]);
+
+/**
+ * Explicit opt-in for a hosted development environment.
+ *
+ * Hosting platforms set a presence indicator on every workload, including
+ * development environments, so the SDK cannot tell a hosted dev environment
+ * from production by presence alone. Setting this variable to a true value
+ * relaxes *platform* indicators only: CI, qualification, and every stage
+ * indicator (`NODE_ENV=production`, `STAGE=staging`, …) still refuse.
+ */
+export const localSqliteHostedOptIn = "TERRASCALE_LOCAL_SQLITE_ALLOW_HOSTED";
+
+/**
+ * Presence indicators the opt-in never relaxes.
+ *
+ * @type {ReadonlySet<string>}
+ */
+export const localSqliteUnrelaxableIndicators = new Set([
+  "CI",
+  "CONTINUOUS_INTEGRATION",
+  "GITHUB_ACTIONS",
+  "GITLAB_CI",
+  "FORGEJO_ACTIONS",
+  "GITEA_ACTIONS",
+  "TF_BUILD",
+  "BUILDKITE",
+  "CIRCLECI",
+  "JENKINS_URL",
+  "TEAMCITY_VERSION",
+  "TERRASCALE_DEPLOYMENT",
+  "TERRASCALE_QUALIFICATION",
+]);
+
+export const localSqliteStageIndicators = /** @type {const} */ ([
+  "NODE_ENV",
+  "APP_ENV",
+  "ENVIRONMENT",
+  "STAGE",
+  "DEPLOY_ENV",
+  "DEPLOYMENT_ENVIRONMENT",
+  "TERRASCALE_ENV",
+  "TERRASCALE_ENVIRONMENT",
+  "VERCEL_ENV",
+]);
+
+const FORBIDDEN_STAGE_PATTERN =
+  /(?:^|[-_.])(?:prod(?:uction)?|stag(?:e|ing)|preview|deploy(?:ed|ment)?|qualif(?:ication|ying|y)|ci)(?:$|[-_.])/iu;
+const FALSE_INDICATOR_VALUES = new Set(["0", "false", "no", "off"]);
+const OPT_IN_VALUES = new Set(["1", "true", "yes", "on", "enabled"]);
+
+/**
+ * @param {Readonly<Record<string, string | undefined>>} [environment]
+ * @returns {void}
+ */
+export function assertLocalSqliteEnvironment(environment = process.env) {
+  const hostedOptIn = OPT_IN_VALUES.has(
+    (environment[localSqliteHostedOptIn] ?? "").trim().toLowerCase(),
+  );
+
+  for (const name of localSqlitePresenceIndicators) {
+    const value = environment[name]?.trim();
+    if (value === undefined || value.length === 0) continue;
+    if (FALSE_INDICATOR_VALUES.has(value.toLowerCase())) continue;
+    if (hostedOptIn && !localSqliteUnrelaxableIndicators.has(name)) continue;
+    throw new TypeError(`SQLite local development mode is disabled when ${name} is set.`);
+  }
+
+  for (const name of localSqliteStageIndicators) {
+    const value = environment[name]?.trim();
+    if (value !== undefined && FORBIDDEN_STAGE_PATTERN.test(value)) {
+      throw new TypeError(`SQLite local development mode is disabled for ${name}=${value}.`);
+    }
+  }
+}

package/src/local/index.js

@@ -0,0 +1,204 @@
+import { isAbsolute } from "node:path";
+import { randomUUID } from "node:crypto";
+import { createTerraBaseClient } from "../database.js";
+import { normalizeLocalBearerToken } from "./authentication.js";
+import { assertLocalSqliteEnvironment } from "./environment.js";
+import { TerraScaleLocalRouter } from "./router.js";
+import { TerraScaleLocalHttpServer } from "./server.js";
+import { TerraScaleSqliteStore } from "./store.js";
+/** @import { TerraBaseClient, TerraBaseClientConfig } from "../database.js" */
+/** @import { CollectionBinding, DatabaseScope } from "../database-types.js" */
+
+/** @typedef {import("./context.js").LocalAuthenticationMode} LocalAuthenticationMode */
+/** @typedef {import("./server.js").LocalServerAddress} LocalServerAddress */
+/** @typedef {import("./better-auth.js").LocalBetterAuthAdapterFactory} LocalBetterAuthAdapterFactory */
+
+/**
+ * @typedef {{
+ *   readonly sqlite: { readonly enabled: true; readonly databasePath: string };
+ *   readonly scope?: DatabaseScope;
+ *   readonly authentication?: LocalAuthenticationMode;
+ *   readonly bearerToken?: string;
+ *   readonly allowRemote?: boolean;
+ * }} TerraScaleSqliteRuntimeOptions
+ */
+/**
+ * @typedef {{
+ *   readonly host?: string;
+ *   readonly port?: number;
+ * }} TerraScaleLocalListenOptions
+ */
+
+/** Explicit Node development backend. Never load this entrypoint in deployment or qualification. */
+export class TerraScaleSqliteRuntime {
+  /** @type {TerraScaleSqliteStore} */
+  #store;
+  /** @type {TerraScaleLocalRouter} */
+  #router;
+  /** @type {TerraScaleLocalHttpServer} */
+  #server;
+  /** @type {string} */
+  #token;
+  /**
+   * @readonly
+   * @type {DatabaseScope}
+   */
+  scope;
+  #closed = false;
+  /** @type {Promise<void> | undefined} */
+  #closePromise;
+  /**
+   * @param {TerraScaleSqliteRuntimeOptions} options
+   */
+  constructor(options) {
+    assertLocalSqliteEnvironment();
+    if (options?.sqlite?.enabled !== true)
+      throw new TypeError("SQLite runtime requires sqlite: { enabled: true }.");
+    if (!isAbsolute(options.sqlite.databasePath))
+      throw new TypeError(
+        "SQLite runtime databasePath must be an absolute path.",
+      );
+    const authentication = options.authentication ?? "permissive";
+    if (authentication !== "permissive" && authentication !== "required")
+      throw new TypeError("Invalid local authentication mode.");
+    if (
+      options.allowRemote !== undefined &&
+      typeof options.allowRemote !== "boolean"
+    )
+      throw new TypeError("allowRemote must be boolean.");
+    if (options.allowRemote === true && authentication !== "required")
+      throw new TypeError(
+        "Remote local listeners require explicit authentication.",
+      );
+    if (authentication === "permissive" && options.bearerToken !== undefined)
+      throw new TypeError("bearerToken requires authentication: required.");
+    this.#token =
+      authentication === "required"
+        ? normalizeLocalBearerToken(options.bearerToken)
+        : "local-development-only";
+    this.#store = new TerraScaleSqliteStore(options.sqlite.databasePath);
+    try {
+      const stored =
+        /** @type {{ tenant: string; database: string; shard: string } | undefined} */ (
+          this.#store.getMeta("local-native-scope")
+        );
+      const scope =
+        options.scope ??
+        (stored === undefined
+          ? { tenant: randomUUID(), database: randomUUID(), shard: 0n }
+          : { ...stored, shard: BigInt(stored.shard) });
+      this.#router = new TerraScaleLocalRouter(this.#store, scope, {
+        authentication,
+        ...(authentication === "required" ? { bearerToken: this.#token } : {}),
+      });
+      this.scope = Object.freeze({ ...scope });
+      this.#store.setMeta("local-native-scope", {
+        ...scope,
+        shard: scope.shard.toString(),
+      });
+      this.#server = new TerraScaleLocalHttpServer(
+        (request) => this.#router.handle(request),
+        { allowRemote: options.allowRemote ?? false },
+      );
+    } catch (error) {
+      this.#store.close();
+      throw error;
+    }
+  }
+  /** @returns {string} */
+  get databasePath() {
+    return this.#store.databasePath;
+  }
+  /** @returns {LocalServerAddress | undefined} */
+  get address() {
+    return this.#server.address;
+  }
+  get authority() {
+    this.#assertOpen();
+    return this.#router.authority;
+  }
+  /**
+   * @param {CollectionBinding} binding
+   * @returns {Promise<void>}
+   */
+  async bindCollection(binding) {
+    this.#assertOpen();
+    await this.#store.exclusive(() => {
+      this.#assertOpen();
+      this.#store.transaction(() => this.#router.bindCollection(binding));
+    });
+  }
+  /**
+   * @param {Pick<TerraBaseClientConfig, "requestTimeoutMs">} [options]
+   * @returns {TerraBaseClient}
+   */
+  createClient(options = {}) {
+    this.#assertOpen();
+    return createTerraBaseClient({
+      ...this.scope,
+      ...options,
+      endpoint: "http://127.0.0.1",
+      apiKey: this.#token,
+      fetch: async (input, init) => {
+        this.#assertOpen();
+        return this.#router.fetch(input, init);
+      },
+    });
+  }
+  /** @returns {Promise<LocalBetterAuthAdapterFactory>} */
+  async createBetterAuthAdapter() {
+    this.#assertOpen();
+    const { createLocalBetterAuthAdapter } = await import("./better-auth.js");
+    this.#assertOpen();
+    return createLocalBetterAuthAdapter(this.#store);
+  }
+  /**
+   * @param {TerraScaleLocalListenOptions} [options]
+   * @returns {Promise<LocalServerAddress>}
+   */
+  start(options = {}) {
+    this.#assertOpen();
+    return this.#server.start(options);
+  }
+  /** @returns {Promise<void>} */
+  stop() {
+    return this.#server.close();
+  }
+  /** @returns {Promise<void>} */
+  async reset() {
+    this.#assertOpen();
+    await this.#store.exclusive(() => {
+      this.#assertOpen();
+      this.#store.reset();
+      this.#router = new TerraScaleLocalRouter(this.#store, this.scope, {
+        authentication: "required",
+        bearerToken: this.#token,
+      });
+      this.#store.setMeta("local-native-scope", {
+        ...this.scope,
+        shard: this.scope.shard.toString(),
+      });
+    });
+  }
+  /** @returns {Promise<void>} */
+  close() {
+    if (this.#closePromise !== undefined) return this.#closePromise;
+    this.#closed = true;
+    this.#closePromise = (async () => {
+      await this.#server.close();
+      await this.#store.exclusive(() => this.#store.close());
+    })();
+    return this.#closePromise;
+  }
+  /** @returns {void} */
+  #assertOpen() {
+    if (this.#closed) throw new Error("The SQLite runtime is closed.");
+  }
+}
+/**
+ * @param {TerraScaleSqliteRuntimeOptions} options
+ * @returns {TerraScaleSqliteRuntime}
+ */
+export function createTerraScaleSqliteRuntime(options) {
+  return new TerraScaleSqliteRuntime(options);
+}