@alchemy.run/turso 0.0.0 → 2.0.0-beta.84

package/src/Group.ts

@@ -0,0 +1,256 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import { Unowned } from "alchemy/AdoptPolicy";
+import { deepEqual, isResolved } from "alchemy/Diff";
+import { createPhysicalName } from "alchemy/PhysicalName";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+/**
+ * A Turso location code, e.g. `"aws-us-east-1"`. List the locations
+ * available to your organization with `turso db locations`.
+ */
+export type Location =
+  | "aws-ap-northeast-1"
+  | "aws-ap-south-1"
+  | "aws-ap-southeast-2"
+  | "aws-ca-central-1"
+  | "aws-eu-north-1"
+  | "aws-eu-west-1"
+  | "aws-sa-east-1"
+  | "aws-us-east-1"
+  | "aws-us-east-2"
+  | "aws-us-west-2"
+  | (string & {});
+
+export interface GroupProps {
+  /**
+   * Group name, unique within the organization. Lowercase letters,
+   * numbers, and dashes. If omitted, a unique name is generated from the
+   * stack, stage, and logical ID. Changing it replaces the group.
+   */
+  name?: string;
+  /**
+   * Primary location of the group. Every database in the group lives here.
+   * Changing it replaces the group (and every database in it).
+   * @default "aws-us-east-1"
+   */
+  location?: Location;
+  /**
+   * Additional replica locations. Reconciled in place by adding and
+   * removing locations. AWS-hosted groups do not support replication, so
+   * this only applies to organizations with legacy Fly-hosted groups.
+   */
+  replicas?: Location[];
+  /**
+   * SQLite extensions enabled for the group's databases: `"all"`, or a list
+   * of extension names. Set at creation; changing it replaces the group.
+   */
+  extensions?: "all" | string[];
+  /**
+   * Prevent the group (and its databases) from being deleted. While
+   * enabled, destroying or replacing the group fails; set it to `false`
+   * and deploy before deleting.
+   * @default false
+   */
+  deleteProtection?: boolean;
+}
+
+export interface GroupAttributes {
+  /** Group name. */
+  name: string;
+  /** Group UUID. */
+  uuid: string;
+  /** The organization slug that owns the group. */
+  organization: string;
+  /** Primary location of the group. */
+  location: string;
+  /** Every location the group runs in (primary first). */
+  locations: string[];
+  /** The libSQL server version the group's databases run. */
+  version: string;
+  /** Whether delete protection is enabled. */
+  deleteProtection: boolean;
+}
+
+export type Group = Resource<"Turso.Group", GroupProps, GroupAttributes, never, Providers>;
+
+/**
+ * A Turso group. Every Turso database belongs to one group, and the group
+ * decides where its databases run.
+ * @see https://docs.turso.tech/concepts#groups
+ *
+ * ### Creating a Group
+ * **Example:** Group in a single location
+ * ```typescript
+ * const group = yield* Turso.Group("Group", {
+ *   location: "aws-us-east-1",
+ * });
+ * ```
+ *
+ * **Example:** Protected group with all extensions enabled
+ * ```typescript
+ * const group = yield* Turso.Group("Group", {
+ *   name: "production",
+ *   location: "aws-eu-west-1",
+ *   extensions: "all",
+ *   deleteProtection: true,
+ * });
+ * ```
+ *
+ * ### Adding databases
+ * **Example:** Create a database in the group
+ * ```typescript
+ * const db = yield* Turso.Database("Db", { group: group.name });
+ * ```
+ *
+ * @resource
+ * @product Group
+ */
+export const Group = Resource<Group>("Turso.Group");
+
+const DEFAULT_LOCATION = "aws-us-east-1";
+
+export const GroupProvider = () =>
+  Provider.effect(
+    Group,
+    Effect.gen(function* () {
+      const groupName = (id: string, name: string | undefined) =>
+        name
+          ? Effect.succeed(name)
+          : createPhysicalName({ id, lowercase: true, maxLength: 32, delimiter: "-" });
+
+      const observe = (org: string, name: string) =>
+        turso.getGroup({ organizationSlug: org, groupName: name }).pipe(
+          Effect.map((res) => res.group),
+          Effect.catchTag("NotFound", () => Effect.succeed(undefined)),
+        );
+
+      const toAttrs = (
+        org: string,
+        group: turso.Group,
+        deleteProtection: boolean,
+      ): GroupAttributes => ({
+        name: group.name!,
+        uuid: group.uuid ?? "",
+        organization: org,
+        location: group.primary ?? "",
+        locations: group.locations ?? [],
+        version: group.version ?? "",
+        deleteProtection,
+      });
+
+      return {
+        stables: ["name", "uuid", "organization", "location"],
+        diff: Effect.fn(function* ({ id, olds, news, output }) {
+          if (!isResolved(news)) return undefined;
+          const name = output?.name ?? (yield* groupName(id, olds?.name));
+          if (news.name !== undefined && news.name !== name) {
+            return { action: "replace" } as const;
+          }
+          if ((news.location ?? DEFAULT_LOCATION) !== (olds?.location ?? DEFAULT_LOCATION)) {
+            return { action: "replace", deleteFirst: news.name !== undefined } as const;
+          }
+          if (!deepEqual(news.extensions, olds?.extensions)) {
+            return { action: "replace", deleteFirst: news.name !== undefined } as const;
+          }
+        }),
+        read: Effect.fn(function* ({ id, olds, output }) {
+          const org = output?.organization ?? (yield* organization);
+          const name = output?.name ?? (yield* groupName(id, olds?.name));
+          const group = yield* observe(org, name);
+          if (!group) return undefined;
+          const attrs = toAttrs(org, group, group.delete_protection ?? false);
+          // Turso has no tags: a group found under an explicit, user-chosen
+          // name without prior state may belong to someone else.
+          return output === undefined && olds?.name !== undefined ? Unowned(attrs) : attrs;
+        }),
+        reconcile: Effect.fn(function* ({ id, news, output, session }) {
+          const org = output?.organization ?? (yield* organization);
+          const name = output?.name ?? (yield* groupName(id, news.name));
+          const location = news.location ?? DEFAULT_LOCATION;
+
+          // Observe
+          let group = yield* observe(org, name);
+
+          // Ensure
+          if (!group) {
+            yield* session.note(`Creating group ${name}...`);
+            group = yield* turso
+              .createGroup({
+                organizationSlug: org,
+                name,
+                location,
+                extensions: news.extensions,
+              })
+              .pipe(
+                Effect.map((res) => res.group),
+                Effect.catchTag("Conflict", () => observe(org, name)),
+              );
+            if (!group) {
+              return yield* Effect.fail(new Error(`Turso group ${name} vanished after create`));
+            }
+          }
+
+          // Sync replica locations against the observed set.
+          const primary = group.primary ?? location;
+          const desired = new Set([primary, ...(news.replicas ?? [])]);
+          const observed = new Set(group.locations ?? [primary]);
+          for (const loc of desired) {
+            if (!observed.has(loc)) {
+              yield* session.note(`Adding location ${loc}...`);
+              group =
+                (yield* turso.addLocationToGroup({
+                  organizationSlug: org,
+                  groupName: name,
+                  location: loc,
+                })).group ?? group;
+            }
+          }
+          for (const loc of observed) {
+            if (!desired.has(loc)) {
+              yield* session.note(`Removing location ${loc}...`);
+              group =
+                (yield* turso.removeLocationFromGroup({
+                  organizationSlug: org,
+                  groupName: name,
+                  location: loc,
+                })).group ?? group;
+            }
+          }
+
+          // Sync configuration.
+          const config = yield* turso.getGroupConfiguration({
+            organizationSlug: org,
+            groupName: name,
+          });
+          let deleteProtection = config.delete_protection ?? false;
+          const desiredProtection = news.deleteProtection ?? false;
+          if (deleteProtection !== desiredProtection) {
+            const updated = yield* turso.updateGroupConfiguration({
+              organizationSlug: org,
+              groupName: name,
+              delete_protection: desiredProtection,
+            });
+            deleteProtection = updated.delete_protection ?? desiredProtection;
+          }
+
+          return toAttrs(org, group, deleteProtection);
+        }),
+        delete: Effect.fn(function* ({ output }) {
+          yield* turso
+            .deleteGroup({ organizationSlug: output.organization, groupName: output.name })
+            .pipe(Effect.catchTag("NotFound", () => Effect.void));
+        }),
+        list: Effect.fn(function* () {
+          const org = yield* organization;
+          const { groups } = yield* turso.listGroups({ organizationSlug: org });
+          return (groups ?? [])
+            .filter((group) => group.name !== undefined)
+            .map((group) => toAttrs(org, group, group.delete_protection ?? false));
+        }),
+      };
+    }),
+  );

package/src/GroupToken.ts

@@ -0,0 +1,119 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import { organization } from "./Credentials.ts";
+import {
+  diffSqlToken,
+  isTokenCurrent,
+  tokenExpiry,
+  type SqlTokenAttributes,
+  type SqlTokenProps,
+} from "./DatabaseToken.ts";
+import type { Providers } from "./Providers.ts";
+
+export interface GroupTokenProps extends SqlTokenProps {
+  /** Name of the group whose databases the token grants access to. */
+  group: string;
+}
+
+export interface GroupTokenAttributes extends SqlTokenAttributes {
+  /** Name of the group the token grants access to. */
+  group: string;
+  /** UUID of the group the token was minted for. */
+  groupId: string;
+}
+
+export type GroupToken = Resource<
+  "Turso.GroupToken",
+  GroupTokenProps,
+  GroupTokenAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * A token that lets an app run SQL on every database in a Turso
+ * {@link Group}, even databases created later. Useful when each customer
+ * has their own database.
+ *
+ * Like {@link DatabaseToken}, you can't cancel a single group token. Changing
+ * a prop creates a new token, but the old one keeps working until it expires.
+ * @see https://docs.turso.tech/api-reference/groups/create-token
+ *
+ * ### Creating a Token
+ * **Example:** Full-access token for every database in a group
+ * ```typescript
+ * const token = yield* Turso.GroupToken("Token", {
+ *   group: group.name,
+ * });
+ * ```
+ *
+ * **Example:** Read-only token that expires after a week
+ * ```typescript
+ * const token = yield* Turso.GroupToken("ReadOnly", {
+ *   group: group.name,
+ *   authorization: "read-only",
+ *   expiration: "7d",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Group
+ */
+export const GroupToken = Resource<GroupToken>("Turso.GroupToken");
+
+export const GroupTokenProvider = () =>
+  Provider.effect(
+    GroupToken,
+    Effect.gen(function* () {
+      return {
+        stables: ["organization"],
+        diff: diffSqlToken,
+        reconcile: Effect.fn(function* ({ news, olds, output }) {
+          const org = output?.organization ?? (yield* organization);
+
+          // Observe — the token is bound to the group's UUID, so a group
+          // replaced under the same name invalidates it.
+          const { group } = yield* turso.getGroup({
+            organizationSlug: org,
+            groupName: news.group,
+          });
+          const groupId = group?.uuid ?? "";
+          if (
+            output !== undefined &&
+            output.group === news.group &&
+            output.groupId === groupId &&
+            (yield* isTokenCurrent(output, olds, news))
+          ) {
+            return output;
+          }
+
+          // Ensure — mint.
+          const authorization = news.authorization ?? "full-access";
+          const { jwt } = yield* turso.createGroupToken({
+            organizationSlug: org,
+            groupName: news.group,
+            authorization,
+            expiration: news.expiration,
+            permissions: news.readAttach
+              ? { read_attach: { databases: news.readAttach } }
+              : undefined,
+          });
+          if (!jwt) {
+            return yield* Effect.fail(new Error(`Turso returned no token for group ${news.group}`));
+          }
+          return {
+            token: jwt,
+            organization: org,
+            authorization,
+            expiresAt: tokenExpiry(jwt),
+            group: news.group,
+            groupId,
+          };
+        }),
+        // Turso cannot revoke a single token; it simply stops being tracked.
+        delete: () => Effect.void,
+      };
+    }),
+  );

package/src/Hrana.ts

@@ -0,0 +1,182 @@
+import { MigrationError, type SqlExecutor } from "@alchemy.run/sql/Migrations";
+import { splitSqlStatements } from "@alchemy.run/sql/SqlFile";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import * as Redacted from "effect/Redacted";
+
+/**
+ * A minimal Hrana-over-HTTP client (`POST /v2/pipeline`) — the SQL wire
+ * protocol every Turso database speaks. Deploy-time work (migrations, SQL
+ * imports) uses it instead of `@libsql/client`, so the provider needs no
+ * driver and runs anywhere `HttpClient` does.
+ *
+ * @see https://github.com/tursodatabase/libsql/blob/main/docs/HRANA_3_SPEC.md
+ */
+export class HranaError extends Data.TaggedError("Turso::HranaError")<{
+  message: string;
+  code?: string;
+  cause?: unknown;
+}> {}
+
+type HranaValue =
+  | { type: "null" }
+  | { type: "integer"; value: string }
+  | { type: "float"; value: number }
+  | { type: "text"; value: string }
+  | { type: "blob"; base64: string };
+
+interface HranaStmt {
+  sql: string;
+  args?: HranaValue[];
+}
+
+interface HranaExecuteResult {
+  cols: Array<{ name: string | null }>;
+  rows: HranaValue[][];
+}
+
+interface HranaError_ {
+  message: string;
+  code?: string;
+}
+
+interface PipelineResponse {
+  results: Array<
+    | { type: "ok"; response: { type: string; result?: unknown } }
+    | { type: "error"; error: HranaError_ }
+  >;
+}
+
+const toHranaValue = (value: unknown): HranaValue => {
+  if (value === null || value === undefined) return { type: "null" };
+  if (typeof value === "bigint") return { type: "integer", value: value.toString() };
+  if (typeof value === "number") {
+    return Number.isInteger(value)
+      ? { type: "integer", value: value.toString() }
+      : { type: "float", value };
+  }
+  if (typeof value === "boolean") return { type: "integer", value: value ? "1" : "0" };
+  if (value instanceof Uint8Array) {
+    return { type: "blob", base64: Buffer.from(value).toString("base64") };
+  }
+  return { type: "text", value: String(value) };
+};
+
+const fromHranaValue = (value: HranaValue): unknown => {
+  switch (value.type) {
+    case "null":
+      return null;
+    case "integer":
+      return Number(value.value);
+    case "float":
+      return value.value;
+    case "text":
+      return value.value;
+    case "blob":
+      return Buffer.from(value.base64, "base64");
+  }
+};
+
+const toRows = (result: HranaExecuteResult): Array<Record<string, unknown>> =>
+  result.rows.map((row) =>
+    Object.fromEntries(
+      result.cols.map((col, i) => [col.name ?? String(i), fromHranaValue(row[i]!)]),
+    ),
+  );
+
+/** Connection details for one Turso database. */
+export interface HranaConnection {
+  /** `https://<hostname>` of the database. */
+  url: string;
+  /** A database auth token (JWT). */
+  authToken: Redacted.Redacted<string>;
+}
+
+const pipeline = (connection: HranaConnection, requests: ReadonlyArray<unknown>) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient;
+    const response = yield* client
+      .execute(
+        HttpClientRequest.post(`${connection.url.replace(/\/$/, "")}/v2/pipeline`).pipe(
+          HttpClientRequest.bearerToken(Redacted.value(connection.authToken)),
+          HttpClientRequest.bodyJsonUnsafe({ requests: [...requests, { type: "close" }] }),
+        ),
+      )
+      .pipe(Effect.mapError((cause) => new HranaError({ message: String(cause), cause })));
+    if (response.status < 200 || response.status >= 300) {
+      const text = yield* response.text.pipe(Effect.orElseSucceed(() => ""));
+      return yield* new HranaError({
+        message: `Turso SQL request failed with HTTP ${response.status}: ${text}`,
+      });
+    }
+    const body = (yield* response.json.pipe(
+      Effect.mapError((cause) => new HranaError({ message: String(cause), cause })),
+    )) as unknown as PipelineResponse;
+    return body.results.slice(0, requests.length);
+  });
+
+/** Execute one statement and return its rows as objects. */
+export const query = (
+  connection: HranaConnection,
+  sql: string,
+  params?: ReadonlyArray<unknown>,
+): Effect.Effect<Array<Record<string, unknown>>, HranaError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const stmt: HranaStmt = { sql, args: (params ?? []).map(toHranaValue) };
+    const [result] = yield* pipeline(connection, [{ type: "execute", stmt }]);
+    if (result === undefined) {
+      return yield* new HranaError({ message: "Turso returned no result" });
+    }
+    if (result.type === "error") {
+      return yield* new HranaError({ message: result.error.message, code: result.error.code });
+    }
+    return toRows(result.response.result as HranaExecuteResult);
+  });
+
+/**
+ * Execute statements atomically. Each entry may hold several
+ * `;`-separated statements (a whole migration file or seed script), so they
+ * run as one Hrana `sequence` wrapped in `BEGIN`/`COMMIT`. A failing
+ * statement stops the sequence before `COMMIT`, and closing the stream
+ * rolls the open transaction back.
+ */
+export const transaction = (
+  connection: HranaConnection,
+  statements: ReadonlyArray<string>,
+): Effect.Effect<void, HranaError, HttpClient.HttpClient> =>
+  Effect.gen(function* () {
+    const body = statements.flatMap(splitSqlStatements);
+    if (body.length === 0) return;
+    const sql = ["BEGIN", ...body.map((s) => s.replace(/;\s*$/, "")), "COMMIT"].join(";\n");
+    const [result] = yield* pipeline(connection, [{ type: "sequence", sql }]);
+    if (result === undefined) {
+      return yield* new HranaError({ message: "Turso returned no result" });
+    }
+    if (result.type === "error") {
+      return yield* new HranaError({ message: result.error.message, code: result.error.code });
+    }
+  });
+
+/** Adapt a Turso database connection into the migration registry's executor. */
+export const makeMigrationExecutor = (
+  connection: HranaConnection,
+  client: HttpClient.HttpClient,
+): SqlExecutor => {
+  const toMigrationError = (error: HranaError) =>
+    new MigrationError({ message: `turso: ${error.message}`, cause: error });
+  return {
+    dialect: "sqlite",
+    query: (sql, params) =>
+      query(connection, sql, params).pipe(
+        Effect.provideService(HttpClient.HttpClient, client),
+        Effect.mapError(toMigrationError),
+      ),
+    batch: (statements) =>
+      transaction(connection, statements).pipe(
+        Effect.provideService(HttpClient.HttpClient, client),
+        Effect.mapError(toMigrationError),
+      ),
+  };
+};