@alchemy.run/modal 0.0.0 → 2.0.0-beta.87

package/src/DictClient.ts

@@ -0,0 +1,166 @@
+import * as dict from "@distilled.cloud/modal/dict";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import { decodeJson, encodeJson, type ModalValueNotJson } from "./BindingHttp.ts";
+import { type OpError, operations } from "./internal.ts";
+
+/** The dict operations the clients call, resolved by `ModalBindings.withCredentials`. */
+export const DictOps = operations({
+  clearDict: dict.clearDict,
+  dictContains: dict.dictContains,
+  dictContents: dict.dictContents,
+  dictLen: dict.dictLen,
+  dictPop: dict.dictPop,
+  getDict: dict.getDict,
+  updateDict: dict.updateDict,
+});
+
+export type DictOps = Effect.Success<typeof DictOps>;
+
+/** A dict call's error: the operation's typed errors, and values that aren't JSON. */
+export type DictError<K extends keyof DictOps> = OpError<DictOps, K> | ModalValueNotJson;
+
+/**
+ * Read access to one dict. Keys and values are JSON: `put("a", { n: 1 })`
+ * stores the bytes of `JSON.stringify`, so Python code reads them with
+ * `json.loads` (Modal's Python client pickles by default).
+ */
+export interface ReadDictClient {
+  readonly dictId: Effect.Effect<string>;
+  /** The value under `key`, or `undefined`. */
+  get<A = unknown>(
+    key: unknown,
+  ): Effect.Effect<A | undefined, DictError<"getDict">, RuntimeContext>;
+  /** Whether `key` is present. */
+  contains(key: unknown): Effect.Effect<boolean, OpError<DictOps, "dictContains">, RuntimeContext>;
+  /** Number of entries. */
+  len(): Effect.Effect<number, OpError<DictOps, "dictLen">, RuntimeContext>;
+  /** Every entry. */
+  entries<A = unknown>(): Effect.Effect<
+    ReadonlyArray<readonly [unknown, A]>,
+    DictError<"dictContents">,
+    RuntimeContext
+  >;
+}
+
+/** Write access to one dict. */
+export interface WriteDictClient {
+  readonly dictId: Effect.Effect<string>;
+  /** Set `key` to `value`; with `ifNotExists`, only when absent (returns whether it wrote). */
+  put(
+    key: unknown,
+    value: unknown,
+    options?: { readonly ifNotExists?: boolean },
+  ): Effect.Effect<boolean, OpError<DictOps, "updateDict">, RuntimeContext>;
+  /** Set many entries at once. */
+  update(
+    entries: Iterable<readonly [unknown, unknown]>,
+  ): Effect.Effect<void, OpError<DictOps, "updateDict">, RuntimeContext>;
+  /** Remove `key` and return its value, or `undefined`. */
+  pop<A = unknown>(
+    key: unknown,
+  ): Effect.Effect<A | undefined, DictError<"dictPop">, RuntimeContext>;
+  /** Remove every entry. */
+  clear(): Effect.Effect<void, OpError<DictOps, "clearDict">, RuntimeContext>;
+}
+
+/** Read and write access to one dict. */
+export interface ReadWriteDictClient extends ReadDictClient, WriteDictClient {}
+
+export const makeReadDictClient = (
+  dictId: Effect.Effect<string>,
+  ops: DictOps,
+): ReadDictClient => ({
+  dictId,
+  get: <A>(key: unknown) =>
+    Effect.gen(function* () {
+      const encodedKey = yield* encodeJson(key);
+      const id = yield* dictId;
+      const response = yield* ops.getDict({
+        dictId: id,
+        key: encodedKey,
+      });
+      return response.found && response.value !== undefined
+        ? yield* decodeJson<A>(response.value)
+        : undefined;
+    }),
+  contains: (key) =>
+    Effect.gen(function* () {
+      const encodedKey = yield* encodeJson(key);
+      const id = yield* dictId;
+      const response = yield* ops.dictContains({
+        dictId: id,
+        key: encodedKey,
+      });
+      return response.found ?? false;
+    }),
+  len: () =>
+    Effect.gen(function* () {
+      const id = yield* dictId;
+      const response = yield* ops.dictLen({ dictId: id });
+      return response.len ?? 0;
+    }),
+  entries: <A>() =>
+    Effect.gen(function* () {
+      const id = yield* dictId;
+      const { items } = yield* ops.dictContents({
+        dictId: id,
+        keys: true,
+        values: true,
+      });
+      return yield* Effect.forEach(items, (entry) =>
+        Effect.all([decodeJson(entry.key ?? ""), decodeJson<A>(entry.value ?? "")] as const),
+      );
+    }),
+});
+
+export const makeWriteDictClient = (
+  dictId: Effect.Effect<string>,
+  ops: DictOps,
+): WriteDictClient => ({
+  dictId,
+  put: (key, value, options = {}) =>
+    Effect.gen(function* () {
+      const encodedKey = yield* encodeJson(key);
+      const id = yield* dictId;
+      const response = yield* ops.updateDict({
+        dictId: id,
+        updates: [{ key: encodedKey, value: yield* encodeJson(value) }],
+        ifNotExists: options.ifNotExists,
+      });
+      return options.ifNotExists ? (response.created ?? false) : true;
+    }),
+  update: (entries) =>
+    Effect.gen(function* () {
+      const updates = yield* Effect.forEach([...entries], ([key, value]) =>
+        Effect.all({ key: encodeJson(key), value: encodeJson(value) }),
+      );
+      const id = yield* dictId;
+      yield* ops.updateDict({ dictId: id, updates });
+    }),
+  pop: <A>(key: unknown) =>
+    Effect.gen(function* () {
+      const encodedKey = yield* encodeJson(key);
+      const id = yield* dictId;
+      const response = yield* ops.dictPop({
+        dictId: id,
+        key: encodedKey,
+      });
+      return response.found && response.value !== undefined
+        ? yield* decodeJson<A>(response.value)
+        : undefined;
+    }),
+  clear: () =>
+    Effect.gen(function* () {
+      const id = yield* dictId;
+      yield* ops.clearDict({ dictId: id });
+    }),
+});
+
+export const makeReadWriteDictClient = (
+  dictId: Effect.Effect<string>,
+  ops: DictOps,
+): ReadWriteDictClient => ({
+  ...makeReadDictClient(dictId, ops),
+  ...makeWriteDictClient(dictId, ops),
+});

package/src/Domain.ts

@@ -0,0 +1,147 @@
+import * as domain from "@distilled.cloud/modal/domain";
+import { isResolved } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import { declarable } from "./internal/Declared.ts";
+import type { Providers } from "./Providers.ts";
+
+export class DomainUnexpectedResponse extends Data.TaggedError("Modal.DomainUnexpectedResponse")<{
+  readonly message: string;
+}> {}
+
+export interface DomainProps {
+  /** The domain name (`agents.example.com`). Changing it replaces the domain. */
+  domainName: string;
+}
+
+/** A DNS record to create at your DNS provider. */
+export interface DomainDnsRecord {
+  readonly type: string;
+  readonly name: string;
+  readonly value: string;
+}
+
+export interface DomainAttributes {
+  /** Domain ID. */
+  domainId: string;
+  /** The domain name. */
+  domainName: string;
+  /** Records to create at your DNS provider before the certificate issues. */
+  dnsRecords: DomainDnsRecord[];
+  /** `pending`, `issued`, `failed` or `revoked`. */
+  certificateStatus: string;
+}
+
+/**
+ * A custom domain for Modal web endpoints, sandbox tunnels
+ * (`customDomain` on `create`) and model endpoints. Create the records in
+ * `dnsRecords` at your DNS provider; Modal issues the certificate once they
+ * resolve.
+ *
+ * :::caution
+ * Modal has no API to remove a domain. Destroying this resource stops
+ * tracking it; remove the domain in the Modal dashboard.
+ * :::
+ *
+ * ### Adding a domain
+ * **Example:** Register a domain and output its DNS records
+ * ```typescript
+ * // alchemy.run.ts
+ * import * as Modal from "@alchemy.run/modal";
+ * import * as Alchemy from "alchemy";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Alchemy.Stack(
+ *   "Agents",
+ *   { providers: Modal.providers() },
+ *   Effect.gen(function* () {
+ *     const agents = yield* Modal.Domain("Agents", { domainName: "agents.example.com" });
+ *     return { records: agents.dnsRecords, certificate: agents.certificateStatus };
+ *   }),
+ * );
+ * ```
+ *
+ * ### Serving a sandbox on it
+ * **Example:** Tunnels on the custom domain
+ * ```typescript
+ * const sandbox = yield* sandboxes.create({
+ *   encryptedPorts: [3000],
+ *   customDomain: "agents.example.com",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Domain
+ */
+export const Domain = declarable<Domain>()(Resource<Domain>("Modal.Domain"));
+
+export type Domain = Resource<"Modal.Domain", DomainProps, DomainAttributes, never, Providers>;
+
+const STATUS: Record<string, string> = {
+  CERTIFICATE_STATUS_PENDING: "pending",
+  CERTIFICATE_STATUS_ISSUED: "issued",
+  CERTIFICATE_STATUS_FAILED: "failed",
+  CERTIFICATE_STATUS_REVOKED: "revoked",
+};
+
+const toAttrs = (d: domain.Domain): DomainAttributes => ({
+  domainId: d.domainId ?? "",
+  domainName: d.domainName ?? "",
+  dnsRecords: (d.dnsRecords ?? []).map((record) => ({
+    type: (record.type ?? "").replace(/^DNS_RECORD_TYPE_/, ""),
+    name: record.name ?? "",
+    value: record.value ?? "",
+  })),
+  certificateStatus: STATUS[d.certificateStatus ?? ""] ?? "pending",
+});
+
+export const DomainProvider = () =>
+  Provider.effect(
+    Domain,
+    Effect.gen(function* () {
+      const observe = Effect.fn(function* (domainName: string) {
+        const { domains } = yield* domain.listDomain({});
+        return (domains ?? []).find((d) => d.domainName === domainName);
+      });
+
+      return {
+        stables: ["domainId", "domainName"],
+        diff: Effect.fn(function* ({ news, olds }) {
+          if (!isResolved(news)) return undefined;
+          return news.domainName !== olds?.domainName
+            ? ({ action: "replace" } as const)
+            : undefined;
+        }),
+        read: Effect.fn(function* ({ olds, output }) {
+          const name = output?.domainName ?? olds?.domainName;
+          if (!name) return undefined;
+          const found = yield* observe(name);
+          return found ? toAttrs(found) : undefined;
+        }),
+        reconcile: Effect.fn(function* ({ news, session }) {
+          // Observe, then ensure; refresh the certificate status either way.
+          let found = yield* observe(news.domainName);
+          if (!found) {
+            yield* session.note(`Adding domain ${news.domainName}...`);
+            yield* domain
+              .createDomain({ domainName: news.domainName })
+              .pipe(Effect.catchTag("DomainAlreadyExists", () => Effect.void));
+            found = yield* observe(news.domainName);
+          }
+          if (!found?.domainId) {
+            return yield* new DomainUnexpectedResponse({
+              message: `Modal domain ${news.domainName} was not listed after create`,
+            });
+          }
+          const verified = yield* domain
+            .verifyDomainCertificate({ domainId: found.domainId })
+            .pipe(Effect.catchTag("DomainNotFound", () => Effect.succeed({ domain: found })));
+          return toAttrs(verified.domain ?? found);
+        }),
+        // Modal has no domain delete RPC; see the caution in the JSDoc.
+        delete: () => Effect.void,
+      };
+    }),
+  );