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

package/src/Website/Vite.ts

@@ -0,0 +1,121 @@
+import { frameworkSite, staticConfigFromAssets, type FrameworkSiteProps } from "./FrameworkSite.ts";
+
+/** The framework-integration package that drives the Vite build. */
+export const VITE_FRAMEWORK_SPECIFIER = "@alchemy.run/frontend-frameworks/vite";
+
+/** The Node container deploy target for the Vite build. */
+export const VITE_NODE_TARGET_SPECIFIER = "@alchemy.run/frontend-frameworks/vite/node";
+
+const viteOptions = (props: ViteProps) =>
+  props.vite !== undefined && (props.vite.outDir !== undefined || props.vite.base !== undefined)
+    ? { vite: props.vite }
+    : undefined;
+
+export interface ViteProps extends FrameworkSiteProps {
+  /**
+   * Serializable Vite config merged OVER the project's own `vite.config.*`
+   * (which loads natively, plugins included).
+   */
+  vite?: {
+    /**
+     * Build output directory, relative to `rootDir`.
+     * @default the project config's `build.outDir` (vite's default: "dist")
+     */
+    outDir?: string;
+    /** Public base path the site deploys under (vite's `base`). */
+    base?: string;
+  };
+}
+
+/**
+ * Deploy a plain [Vite](https://vite.dev) application to Fly: a Service
+ * serving the `vite build` output from a tiny static-file server. For
+ * client-only projects — React/Vue/Solid SPAs, `index.html` multi-page
+ * apps — whose entire deployable output is static assets.
+ *
+ * The build runs through `@alchemy.run/frontend-frameworks/vite` with the
+ * `@alchemy.run/frontend-frameworks/vite/node` deploy target — the package
+ * must be installed in your project. Your project's own `vite.config.*`
+ * (plugins included) drives the build.
+ *
+ * During `alchemy dev` the site is Vite's own dev server (native HMR) and
+ * no cloud resources are created — the site's `url` is the dev server's
+ * local address. `Alchemy.remote()` opts back into the full deployment.
+ *
+ *
+ * ### Creating Vite Sites
+ * **Example:** Basic Vite SPA
+ * ```typescript
+ * const site = yield* Fly.Website.Vite("Web");
+ * ```
+ *
+ * **Example:** Project in a Subdirectory
+ * ```typescript
+ * const site = yield* Fly.Website.Vite("Web", {
+ *   rootDir: "./app",
+ * });
+ * ```
+ *
+ * **Example:** Existing App
+ * ```typescript
+ * const site = yield* Fly.Website.Vite("Web", { app: Site });
+ * ```
+ *
+ * ### Multi-Page Sites
+ * **Example:** Per-Route HTML Pages with a 404 Page
+ * ```typescript
+ * const site = yield* Fly.Website.Vite("Docs", {
+ *   assets: { notFoundHandling: "404-page" },
+ * });
+ * ```
+ *
+ * ### Custom Domain
+ * **Example:** ACME on an existing hostname
+ * ```typescript
+ * const site = yield* Fly.Website.Vite("Web", {
+ *   domain: "app.example.com",
+ * });
+ * ```
+ *
+ * **Example:** Publish DNS in Cloudflare
+ * ```typescript
+ * // The ACME challenge CNAME and A/AAAA records are published in the
+ * // Cloudflare zone. Requires Cloudflare.providers() in the stack.
+ * const site = yield* Fly.Website.Vite("Web", {
+ *   domain: { name: "app.example.com", dns: Cloudflare.DNS.Adapter() },
+ * });
+ * ```
+ *
+ * ### Build Configuration
+ * **Example:** Custom Output Directory and Base Path
+ * ```typescript
+ * const site = yield* Fly.Website.Vite("Docs", {
+ *   vite: { outDir: "build", base: "/docs/" },
+ * });
+ * ```
+ *
+ * ### Local Development
+ * **Example:** Vite Dev Server Under `alchemy dev`
+ * ```typescript
+ * // `alchemy dev` starts `vite` programmatically: site.url is the local
+ * // dev server (HMR included); no Fly App or Service is created.
+ * const site = yield* Fly.Website.Vite("Web");
+ * ```
+ *
+ * @resource
+ * @product Website
+ */
+export const Vite = (id: string, props: ViteProps = {}) =>
+  frameworkSite(id, props, {
+    name: "Vite",
+    framework: VITE_FRAMEWORK_SPECIFIER,
+    target: VITE_NODE_TARGET_SPECIFIER,
+    options: {
+      ...viteOptions(props),
+      notFoundHandling: "spa",
+      htmlHandling: props.assets?.htmlHandling,
+    },
+    static: staticConfigFromAssets(props.assets, {
+      notFoundHandling: "single-page-application",
+    }),
+  });

package/src/Website/Vocs.ts

@@ -0,0 +1,50 @@
+import { frameworkSite, type FrameworkSiteProps } from "./FrameworkSite.ts";
+
+/** The framework-integration package that drives the Vocs build. */
+export const VOCS_FRAMEWORK_SPECIFIER = "@alchemy.run/frontend-frameworks/vocs/node";
+
+/** The Node container deploy target for the Vocs build. */
+export const VOCS_NODE_TARGET_SPECIFIER = "@alchemy.run/frontend-frameworks/vocs/node";
+
+export interface VocsProps extends FrameworkSiteProps {
+  /**
+   * Vocs build output directory, relative to {@link FrameworkSiteProps.rootDir}.
+   * Set this when `vocs.config.*` customizes `outDir`.
+   * @default "dist"
+   */
+  outDir?: string;
+}
+
+/**
+ * Deploy a [Vocs](https://vocs.dev) documentation site to Fly. The node
+ * target serves static assets first, then Vocs' Waku RSC handler
+ * (`/about` → `about/index.html`, otherwise SSR).
+ *
+ *
+ * ### Creating Vocs Sites
+ * **Example:** Vocs documentation site
+ * ```typescript
+ * const docs = yield* Fly.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ * });
+ * ```
+ *
+ * **Example:** Custom output directory
+ * ```typescript
+ * const docs = yield* Fly.Website.Vocs("Docs", {
+ *   rootDir: "./docs",
+ *   outDir: "build",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Website
+ */
+export const Vocs = (id: string, props: VocsProps = {}) =>
+  frameworkSite(id, props, {
+    name: "Vocs",
+    framework: VOCS_FRAMEWORK_SPECIFIER,
+    target: VOCS_NODE_TARGET_SPECIFIER,
+    options: props.outDir !== undefined ? { outDir: props.outDir } : undefined,
+    htmlHandling: "drop-trailing-slash",
+  });

package/src/Website/Waku.ts

@@ -0,0 +1,65 @@
+import { frameworkSite, type FrameworkSiteProps } from "./FrameworkSite.ts";
+
+/** The framework-integration package that drives the Waku build. */
+export const WAKU_FRAMEWORK_SPECIFIER = "@alchemy.run/frontend-frameworks/waku";
+
+/** The Node container deploy target for the Waku build. */
+export const WAKU_NODE_TARGET_SPECIFIER = "@alchemy.run/frontend-frameworks/waku/node";
+
+const wakuOptions = (props: WakuProps) =>
+  props.waku !== undefined ? { waku: props.waku } : undefined;
+
+export interface WakuProps extends FrameworkSiteProps {
+  /**
+   * Serializable Waku config merged OVER the project's own
+   * `waku.config.*`.
+   */
+  waku?: {
+    /**
+     * Source directory, relative to `rootDir` (waku's `srcDir`).
+     * @default the project's `waku.config.*` value, or `"src"`
+     */
+    srcDir?: string;
+    /**
+     * Build output directory (waku's `distDir`).
+     * @default the project's `waku.config.*` value, or `"dist"`
+     */
+    distDir?: string;
+    /** Public base path the site deploys under (waku's `basePath`). */
+    basePath?: string;
+  };
+}
+
+/**
+ * Deploy a [Waku](https://waku.gg) application to Fly: the RSC server on a
+ * Machine, static assets (SSG pages included) baked into the image.
+ * Prerendered pages are served extensionless (`/about`).
+ *
+ *
+ * ### Creating Waku Sites
+ * **Example:** Basic Waku App
+ * ```typescript
+ * const site = yield* Fly.Website.Waku("Web", {
+ *   rootDir: "./app",
+ * });
+ * ```
+ *
+ * **Example:** Custom Domain
+ * ```typescript
+ * const site = yield* Fly.Website.Waku("Web", {
+ *   rootDir: "./app",
+ *   domain: "app.example.com",
+ * });
+ * ```
+ *
+ * @resource
+ * @product Website
+ */
+export const Waku = (id: string, props: WakuProps = {}) =>
+  frameworkSite(id, props, {
+    name: "Waku",
+    framework: WAKU_FRAMEWORK_SPECIFIER,
+    target: WAKU_NODE_TARGET_SPECIFIER,
+    options: wakuOptions(props),
+    htmlHandling: "drop-trailing-slash",
+  });

package/src/Website/index.ts

@@ -0,0 +1,16 @@
+export * from "./AssetDeployment.ts";
+export * from "./Astro.ts";
+export * from "./Foldkit.ts";
+export * from "./FrameworkSite.ts";
+export * from "./Nextjs.ts";
+export * from "./Nuxt.ts";
+export * from "./Octane.ts";
+export * from "./ReactRouter.ts";
+export * from "./SolidStart.ts";
+export * from "./StaticSite.ts";
+export * from "./SvelteKit.ts";
+export * from "./TanStackStart.ts";
+export * from "./Vinext.ts";
+export * from "./Vite.ts";
+export * from "./Vocs.ts";
+export * from "./Waku.ts";

package/src/WriteCertificates.ts

@@ -0,0 +1,90 @@
+import type {
+  CertificateCheckResponse,
+  CertificateDetail,
+  CheckAppCertificateError,
+  CreateAppAcmeCertificateError,
+  CreateAppCustomCertificateError,
+  DeleteAppCertificateError,
+  DeleteAppCustomCertificateError,
+  GetAppCertificateError,
+} from "@distilled.cloud/fly-io/machines";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import type * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { App } from "./App.ts";
+
+/**
+ * Manage an App's TLS certificates at runtime — the companion to the
+ * deploy-time {@link Certificate} resource, for services that mint or
+ * rotate certificates on their own (a relay adding a tenant's wildcard,
+ * a renewal loop).
+ *
+ * The App is fixed by `WriteCertificates(app)`; calls take a hostname.
+ *
+ * ### Fly-managed (Let's Encrypt)
+ * **Example:** Request and check
+ * ```typescript
+ * const certs = yield* Fly.WriteCertificates(Site);
+ * const requested = yield* certs.request("www.example.com");
+ * // publish requested.dns_requirements, then:
+ * const status = yield* certs.check("www.example.com");
+ * ```
+ *
+ * ### Bring your own PEM
+ * A certificate issued elsewhere (an `ACME.IssueCertificate` wildcard
+ * from ZeroSSL, say) goes up as a custom certificate.
+ *
+ * **Example:** Upload
+ * ```typescript
+ * yield* certs.upload({
+ *   hostname: "*.tenant.example.com",
+ *   fullchain: issued.chain,
+ *   privateKey: issued.privateKey,
+ * });
+ * ```
+ *
+ * @binding
+ * @product Certificate
+ */
+export interface WriteCertificates extends Binding.Service<
+  WriteCertificates,
+  "Fly.WriteCertificates",
+  (app: App) => Effect.Effect<WriteCertificatesClient>
+> {}
+
+export const WriteCertificates = Binding.Service<WriteCertificates>("Fly.WriteCertificates");
+
+export interface UploadCertificateRequest {
+  readonly hostname: string;
+  /** PEM chain, leaf first. */
+  readonly fullchain: string;
+  /** PEM private key. */
+  readonly privateKey: Redacted.Redacted<string> | string;
+}
+
+/** Certificate operations on one App. */
+export interface WriteCertificatesClient {
+  /** Request a Fly-managed (Let's Encrypt) certificate. Idempotent. */
+  request(
+    hostname: string,
+  ): Effect.Effect<CertificateDetail | undefined, CreateAppAcmeCertificateError, RuntimeContext>;
+  /** Upload a custom PEM. Replaces an existing custom certificate. */
+  upload(
+    request: UploadCertificateRequest,
+  ): Effect.Effect<
+    CertificateDetail | undefined,
+    CreateAppCustomCertificateError | DeleteAppCustomCertificateError,
+    RuntimeContext
+  >;
+  /** Re-run Fly's validation checks for the hostname. */
+  check(
+    hostname: string,
+  ): Effect.Effect<CertificateCheckResponse, CheckAppCertificateError, RuntimeContext>;
+  /** The certificate for a hostname, or `undefined`. */
+  get(
+    hostname: string,
+  ): Effect.Effect<CertificateDetail | undefined, GetAppCertificateError, RuntimeContext>;
+  /** Remove the hostname's certificate. Missing counts as removed. */
+  remove(hostname: string): Effect.Effect<void, DeleteAppCertificateError, RuntimeContext>;
+}

package/src/WriteCertificatesHttp.ts

@@ -0,0 +1,93 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.ts";
+import { type SecretAuth, makeHttpAppBinding, unwrapSecretValue } from "./SecretHttp.ts";
+import { WriteCertificates, type WriteCertificatesClient } from "./WriteCertificates.ts";
+
+/**
+ * HTTP implementation of {@link WriteCertificates}. Provide it on the
+ * {@link Service} or Action Effect.
+ *
+ * ### Provide the layer
+ * **Example:** On a Service
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const certs = yield* Fly.WriteCertificates(Site);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.WriteCertificatesHttp))
+ * ```
+ *
+ * @layer
+ * @product Certificate
+ * @provides Fly.WriteCertificates
+ */
+export const WriteCertificatesHttp = Layer.effect(
+  WriteCertificates,
+  Effect.suspend(() =>
+    makeHttpAppBinding<WriteCertificatesClient>({
+      makeClient: certificatesWriteClient,
+    }),
+  ),
+).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));
+
+/** Build the client over an injectable auth and App name. */
+export const certificatesWriteClient = (
+  auth: SecretAuth,
+  appName: Effect.Effect<string>,
+): WriteCertificatesClient => {
+  const authorize = auth.authorize;
+  return {
+    request: Effect.fn("Fly.Certificates.request")(function* (hostname) {
+      return yield* authorize(
+        machines
+          .createAppAcmeCertificate({ app_name: yield* appName, hostname })
+          .pipe(Effect.catchTag("Conflict", () => Effect.undefined)),
+      );
+    }),
+    upload: Effect.fn("Fly.Certificates.upload")(function* (request) {
+      const app_name = yield* appName;
+      const body = {
+        app_name,
+        hostname: request.hostname,
+        fullchain: request.fullchain,
+        private_key: unwrapSecretValue(request.privateKey),
+      };
+      return yield* authorize(
+        machines.createAppCustomCertificate(body).pipe(
+          // An existing custom certificate conflicts: replace it.
+          Effect.catchTag("Conflict", () =>
+            machines
+              .deleteAppCustomCertificate({
+                app_name,
+                hostname: request.hostname,
+              })
+              .pipe(
+                Effect.catchTag("NotFound", () => Effect.void),
+                Effect.andThen(machines.createAppCustomCertificate(body)),
+              ),
+          ),
+        ),
+      );
+    }),
+    check: Effect.fn("Fly.Certificates.check")(function* (hostname) {
+      return yield* authorize(machines.checkAppCertificate({ app_name: yield* appName, hostname }));
+    }),
+    get: Effect.fn("Fly.Certificates.get")(function* (hostname) {
+      return yield* authorize(
+        machines
+          .getAppCertificate({ app_name: yield* appName, hostname })
+          .pipe(Effect.catchTag("NotFound", () => Effect.undefined)),
+      );
+    }),
+    remove: Effect.fn("Fly.Certificates.remove")(function* (hostname) {
+      return yield* authorize(
+        machines.deleteAppCertificate({ app_name: yield* appName, hostname }).pipe(
+          Effect.catchTag("NotFound", () => Effect.void),
+          Effect.asVoid,
+        ),
+      );
+    }),
+  };
+};

package/src/WriteRedis.ts

@@ -0,0 +1,31 @@
+import type { WriteClient } from "@alchemy.run/redis";
+import * as Binding from "alchemy/Binding";
+import type * as Effect from "effect/Effect";
+import type { Redis } from "./Redis.ts";
+
+/**
+ * Bind a {@link Redis} database with write access (`set`, `del`).
+ *
+ * `WriteRedis` is the Context tag, the type, and the callable —
+ * `yield* Fly.WriteRedis(Cache)`. Provide {@link WriteRedisHttp}.
+ *
+ *
+ * ### Write
+ * **Example:** Set a key
+ * ```typescript
+ * const cache = yield* Fly.WriteRedis(Cache);
+ * yield* cache.set("marker", "hello");
+ * ```
+ *
+ * @binding
+ * @product Redis
+ */
+export interface WriteRedis extends Binding.Service<
+  WriteRedis,
+  "Fly.WriteRedis",
+  (redis: Redis) => Effect.Effect<WriteRedisClient>
+> {}
+
+export const WriteRedis = Binding.Service<WriteRedis>("Fly.WriteRedis");
+
+export type WriteRedisClient = WriteClient;

package/src/WriteRedisHttp.ts

@@ -0,0 +1,18 @@
+import * as Layer from "effect/Layer";
+import { makeRedisBinding } from "./RedisBinding.ts";
+import { makeWriteRedisClient } from "./RedisHttp.ts";
+import { WriteRedis } from "./WriteRedis.ts";
+
+/**
+ * HTTP implementation of {@link WriteRedis}.
+ *
+ * @layer
+ * @product Redis
+ * @provides Fly.WriteRedis
+ */
+export const WriteRedisHttp = Layer.effect(
+  WriteRedis,
+  makeRedisBinding({
+    makeClient: makeWriteRedisClient,
+  }),
+);

package/src/WriteSecret.ts

@@ -0,0 +1,86 @@
+import type {
+  AppSecretsUpdateResp,
+  DeleteAppSecretResponse,
+  CreateSecretError,
+  DeleteSecretError,
+  UpdateSecretsError,
+  SetAppSecretResponse,
+} from "@distilled.cloud/fly-io/machines";
+import * as Binding from "alchemy/Binding";
+import type { RuntimeContext } from "alchemy/RuntimeContext";
+import * as Effect from "effect/Effect";
+import type * as Redacted from "effect/Redacted";
+import type { Secret } from "./Secret.ts";
+
+/**
+ * Create, update, and delete Fly.io App secrets at runtime.
+ *
+ * The App is fixed by `WriteSecret(secret)`. Calls take no
+ * `app_name`. Inside a {@link Machine} or {@link Service}, Alchemy
+ * mints an App deploy token. Inside an Action, the ambient
+ * `FLY_API_TOKEN` is used.
+ *
+ *
+ * ### Create
+ * Bind the client in init. Provide {@link WriteSecretHttp}. Wrap
+ * values with `Redacted.make`.
+ *
+ * **Example:** Create a secret
+ * ```typescript
+ * const Seed = Alchemy.Action(
+ *   "Seed",
+ *   Effect.gen(function* () {
+ *     const secrets = yield* Fly.WriteSecret(ApiToken);
+ *
+ *     return Effect.fn(function* () {
+ *       yield* secrets.create("API_KEY", Redacted.make("sk_live"));
+ *     });
+ *   }).pipe(Effect.provide(Fly.WriteSecretHttp)),
+ * );
+ * ```
+ *
+ * ### Update
+ * `update` rotates by name (batch of one).
+ *
+ * **Example:** Rotate
+ * ```typescript
+ * yield* secrets.update("API_KEY", Redacted.make("sk_live_rotated"));
+ * ```
+ *
+ * ### Delete
+ * `delete` removes a secret by name.
+ *
+ * **Example:** Delete
+ * ```typescript
+ * yield* secrets.delete("API_KEY");
+ * ```
+ *
+ * @binding
+ * @product Secret
+ */
+export interface WriteSecret extends Binding.Service<
+  WriteSecret,
+  "Fly.WriteSecret",
+  (secret: Secret) => Effect.Effect<WriteSecretClient>
+> {}
+
+export const WriteSecret = Binding.Service<WriteSecret>("Fly.WriteSecret");
+
+/**
+ * Mutating App secret operations. The App is fixed when the client is
+ * bound, so no `app_name` is passed per call.
+ */
+export interface WriteSecretClient {
+  /** Create or upsert a secret by name. */
+  create(
+    name: string,
+    value: Redacted.Redacted<string> | string,
+  ): Effect.Effect<SetAppSecretResponse, CreateSecretError, RuntimeContext>;
+  /** Update secrets by name (batch of one). */
+  update(
+    name: string,
+    value: Redacted.Redacted<string> | string,
+  ): Effect.Effect<AppSecretsUpdateResp, UpdateSecretsError, RuntimeContext>;
+  /** Delete a secret by name. */
+  delete(name: string): Effect.Effect<DeleteAppSecretResponse, DeleteSecretError, RuntimeContext>;
+}

package/src/WriteSecretHttp.ts

@@ -0,0 +1,71 @@
+import * as machines from "@distilled.cloud/fly-io/machines";
+import * as Effect from "effect/Effect";
+import * as FetchHttpClient from "effect/http/FetchHttpClient";
+import * as Layer from "effect/Layer";
+import { CredentialsFromAmbientOrEnv } from "./Credentials.ts";
+import type { Secret } from "./Secret.ts";
+import { type SecretAuth, makeHttpSecretBinding, unwrapSecretValue } from "./SecretHttp.ts";
+import { WriteSecret, type WriteSecretClient } from "./WriteSecret.ts";
+
+/**
+ * HTTP implementation of {@link WriteSecret}. Provide it on the
+ * {@link Service} or Action Effect.
+ *
+ *
+ * ### Provide the layer
+ * **Example:** On an Action
+ * ```typescript
+ * Effect.gen(function* () {
+ *   const secrets = yield* Fly.WriteSecret(ApiToken);
+ *   // ...
+ * }).pipe(Effect.provide(Fly.WriteSecretHttp))
+ * ```
+ *
+ * @layer
+ * @product Secret
+ * @provides Fly.WriteSecret
+ */
+export const WriteSecretHttp = Layer.effect(
+  WriteSecret,
+  Effect.suspend(() =>
+    makeHttpSecretBinding<Secret, WriteSecretClient>({
+      makeClient: secretWriteClient,
+    }),
+  ),
+).pipe(Layer.provide(FetchHttpClient.layer), Layer.provide(CredentialsFromAmbientOrEnv));
+
+/** Build the write client over an injectable auth and App name. */
+export const secretWriteClient = (
+  auth: SecretAuth,
+  appName: Effect.Effect<string>,
+  _secretName: Effect.Effect<string>,
+): WriteSecretClient => {
+  const authorize = auth.authorize;
+  return {
+    create: Effect.fn("Fly.Secret.create")(function* (name, value) {
+      return yield* authorize(
+        machines.createSecret({
+          app_name: yield* appName,
+          secret_name: name,
+          value: unwrapSecretValue(value),
+        }),
+      );
+    }),
+    update: Effect.fn("Fly.Secret.update")(function* (name, value) {
+      return yield* authorize(
+        machines.updateSecrets({
+          app_name: yield* appName,
+          values: { [name]: unwrapSecretValue(value) },
+        }),
+      );
+    }),
+    delete: Effect.fn("Fly.Secret.delete")(function* (name) {
+      return yield* authorize(
+        machines.deleteSecret({
+          app_name: yield* appName,
+          secret_name: name,
+        }),
+      );
+    }),
+  };
+};