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

package/src/DatabaseToken.ts

@@ -0,0 +1,213 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import { deepEqual } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Clock from "effect/Clock";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Redacted from "effect/Redacted";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+export class DatabaseTokenUnexpectedResponse extends Data.TaggedError(
+  "DatabaseTokenUnexpectedResponse",
+)<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/** Access level of a Turso SQL auth token. */
+export type TokenAuthorization = "full-access" | "read-only";
+
+/** Props shared by {@link DatabaseToken} and {@link GroupToken}. */
+export interface SqlTokenProps {
+  /**
+   * Access level granted by the token.
+   * @default "full-access"
+   */
+  authorization?: TokenAuthorization;
+  /**
+   * Token lifetime, e.g. `"2w"`, `"7d"`, `"1h30m"`. Omit for a token that
+   * never expires. An expired token is re-minted on the next deploy.
+   */
+  expiration?: string;
+  /**
+   * Databases this token may `ATTACH` for reading (requires `allowAttach`
+   * on those databases). Not supported on AWS-hosted databases.
+   */
+  readAttach?: string[];
+}
+
+/** Attributes shared by {@link DatabaseToken} and {@link GroupToken}. */
+export interface SqlTokenAttributes {
+  /** The token (a JWT), sent as `Authorization: Bearer <token>`. */
+  token: Redacted.Redacted<string>;
+  /** The organization slug the token belongs to. */
+  organization: string;
+  /** Access level granted by the token. */
+  authorization: TokenAuthorization;
+  /** Expiry as epoch milliseconds, or `undefined` for a non-expiring token. */
+  expiresAt: number | undefined;
+}
+
+export interface DatabaseTokenProps extends SqlTokenProps {
+  /** Name of the database the token grants access to (e.g. `db.name`). */
+  database: string;
+}
+
+export interface DatabaseTokenAttributes extends SqlTokenAttributes {
+  /** Name of the database the token grants access to. */
+  database: string;
+  /** UUID of the database the token was minted for. */
+  dbId: string;
+}
+
+export type DatabaseToken = Resource<
+  "Turso.DatabaseToken",
+  DatabaseTokenProps,
+  DatabaseTokenAttributes,
+  never,
+  Providers
+>;
+
+/**
+ * A token that lets an app run SQL on one Turso database. Workers and
+ * Lambdas should use {@link Connect}, which creates one for you. Use
+ * `DatabaseToken` for anything else, such as a container or a CI job.
+ *
+ * You can't cancel a single token. Changing a prop creates a new token, but
+ * the old one keeps working until it expires. Destroying the resource doesn't
+ * stop it either. Give tokens you share an `expiration`, or cancel every token
+ * for the database with `turso db tokens invalidate`.
+ * @see https://docs.turso.tech/api-reference/databases/create-token
+ *
+ * ### Creating a Token
+ * **Example:** Full-access token
+ * ```typescript
+ * const token = yield* Turso.DatabaseToken("Token", {
+ *   database: db.name,
+ * });
+ * ```
+ *
+ * **Example:** Read-only token that expires after two weeks
+ * ```typescript
+ * const token = yield* Turso.DatabaseToken("ReadOnly", {
+ *   database: db.name,
+ *   authorization: "read-only",
+ *   expiration: "2w",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Database
+ */
+export const DatabaseToken = Resource<DatabaseToken>("Turso.DatabaseToken");
+
+/** Decode a Turso JWT's `exp` claim (seconds) to epoch milliseconds. */
+export const tokenExpiry = (token: Redacted.Redacted<string>): number | undefined => {
+  const payload = Redacted.value(token).split(".")[1];
+  if (!payload) return undefined;
+  try {
+    const claims = JSON.parse(Buffer.from(payload, "base64url").toString("utf8")) as {
+      exp?: number;
+    };
+    return typeof claims.exp === "number" ? claims.exp * 1000 : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+/** Re-mint a token that expires within the hour. */
+const RENEW_WITHIN_MS = 60 * 60 * 1000;
+
+/**
+ * `diff` for SQL tokens: an unchanged token that is about to expire still
+ * needs an update, so the deploy re-mints it.
+ */
+export const diffSqlToken = Effect.fn(function* ({
+  output,
+}: {
+  output: SqlTokenAttributes | undefined;
+}) {
+  if (output?.expiresAt === undefined) return undefined;
+  const now = yield* Clock.currentTimeMillis;
+  return output.expiresAt - now <= RENEW_WITHIN_MS ? ({ action: "update" } as const) : undefined;
+});
+
+/** Whether a previously minted token can be kept as-is. */
+export const isTokenCurrent = Effect.fn(function* (
+  output: SqlTokenAttributes | undefined,
+  olds: SqlTokenProps | undefined,
+  news: SqlTokenProps,
+) {
+  if (output === undefined || olds === undefined) return false;
+  if (
+    (news.authorization ?? "full-access") !== (olds.authorization ?? "full-access") ||
+    news.expiration !== olds.expiration ||
+    !deepEqual(news.readAttach ?? [], olds.readAttach ?? [])
+  ) {
+    return false;
+  }
+  if (output.expiresAt === undefined) return true;
+  // Re-mint a token that expires within the hour, so a deploy never hands
+  // consumers a token about to lapse.
+  const now = yield* Clock.currentTimeMillis;
+  return output.expiresAt - now > RENEW_WITHIN_MS;
+});
+
+export const DatabaseTokenProvider = () =>
+  Provider.effect(
+    DatabaseToken,
+    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 database's UUID, so a
+          // database replaced under the same name invalidates it.
+          const { database } = yield* turso.getDatabase({
+            organizationSlug: org,
+            databaseName: news.database,
+          });
+          const dbId = database?.DbId ?? "";
+          if (
+            output !== undefined &&
+            output.database === news.database &&
+            output.dbId === dbId &&
+            (yield* isTokenCurrent(output, olds, news))
+          ) {
+            return output;
+          }
+
+          // Ensure — mint.
+          const authorization = news.authorization ?? "full-access";
+          const { jwt } = yield* turso.createDatabaseToken({
+            organizationSlug: org,
+            databaseName: news.database,
+            authorization,
+            expiration: news.expiration,
+            permissions: news.readAttach
+              ? { read_attach: { databases: news.readAttach } }
+              : undefined,
+          });
+          if (!jwt) {
+            return yield* new DatabaseTokenUnexpectedResponse({
+              message: `Turso returned no token for ${news.database}`,
+            });
+          }
+          return {
+            token: jwt,
+            organization: org,
+            authorization,
+            expiresAt: tokenExpiry(jwt),
+            database: news.database,
+            dbId,
+          };
+        }),
+        // Turso cannot revoke a single token; it simply stops being tracked.
+        delete: () => Effect.void,
+      };
+    }),
+  );

package/src/Group.ts

@@ -0,0 +1,269 @@
+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 Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { organization } from "./Credentials.ts";
+import type { Providers } from "./Providers.ts";
+
+export class GroupUnexpectedResponse extends Data.TaggedError("GroupUnexpectedResponse")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+/**
+ * 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.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, previous }) {
+          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 — unless it
+          // is the generation a delete-first replacement is about to free.
+          const ours =
+            output !== undefined ||
+            olds?.name === undefined ||
+            (previous?.organization === org && previous.name === name);
+          return ours ? attrs : Unowned(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* new GroupUnexpectedResponse({
+                message: `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,127 @@
+import * as turso from "@distilled.cloud/turso/turso";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Data from "effect/Data";
+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 class GroupTokenUnexpectedResponse extends Data.TaggedError("GroupTokenUnexpectedResponse")<{
+  readonly message: string;
+  readonly cause?: unknown;
+}> {}
+
+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* new GroupTokenUnexpectedResponse({
+              message: `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,
+      };
+    }),
+  );