@samebase/convex-hosting 0.0.0-stage → 0.3.1

package/src/client/index.ts

@@ -0,0 +1,355 @@
+import {
+  httpActionGeneric,
+  queryGeneric,
+  type GenericActionCtx,
+  type GenericDataModel,
+  type HttpRouter,
+} from "convex/server";
+import { v, type GenericId } from "convex/values";
+import type { ComponentApi } from "../component/_generated/component.js";
+import {
+  cacheControlFor,
+  decodeRequestPath,
+  etagMatches,
+  getMimeType,
+  getSetupHtml,
+  isHtmlContentType,
+} from "../component/serving.js";
+
+const deploymentInfoValidator = v.object({
+  _id: v.string(),
+  _creationTime: v.number(),
+  currentDeploymentId: v.string(),
+  deployedAt: v.number(),
+  spaFallback: v.optional(v.boolean()),
+});
+
+type CdnBaseUrl = string | ((request: Request) => string);
+
+/** The parts of an action context needed to serve a static file. */
+type AssetServingCtx = Pick<GenericActionCtx<GenericDataModel>, "runQuery" | "storage">;
+
+/**
+ * Register app-owned HTTP routes for the hosted site.
+ *
+ * Prefer mounting the component's own HTTP routes when it can own the URL
+ * prefix. Use this compatibility mode when existing app HTTP routes must stay
+ * at the same root. Exact app routes take precedence over this catch-all.
+ * Assets and deployment state still live in the component.
+ *
+ * @example
+ * ```typescript
+ * // convex/convex.config.ts
+ * const app = defineApp();
+ * app.use(hosting); // no httpPrefix: the app owns HTTP routing
+ *
+ * // convex/http.ts
+ * const http = httpRouter();
+ * auth.addHttpRoutes(http);
+ * registerStaticRoutes(http, components.hosting);
+ * export default http;
+ * ```
+ */
+export function registerStaticRoutes(
+  http: HttpRouter,
+  component: ComponentApi,
+  {
+    pathPrefix = "/",
+    spaFallback,
+    cdnBaseUrl,
+  }: {
+    /** URL prefix where the app should serve static files. */
+    pathPrefix?: string;
+    /** Override the deployment's SPA fallback setting. */
+    spaFallback?: boolean;
+    /** Optional custom base URL for convex-fs blob redirects. */
+    cdnBaseUrl?: CdnBaseUrl;
+  } = {},
+) {
+  if (!pathPrefix.startsWith("/")) {
+    throw new Error("pathPrefix must start with /");
+  }
+
+  const normalizedPrefix = pathPrefix === "/" ? "" : pathPrefix.replace(/\/$/, "");
+
+  const serveStaticFile = httpActionGeneric(async (ctx, request) => {
+    const decodedPath = decodeRequestPath(new URL(request.url).pathname);
+    if (decodedPath === null) {
+      return new Response("Bad Request", {
+        status: 400,
+        headers: { "Content-Type": "text/plain" },
+      });
+    }
+    let path = decodedPath;
+
+    if (normalizedPrefix && path.startsWith(normalizedPrefix)) {
+      path = path.slice(normalizedPrefix.length) || "/";
+    }
+    if (path === "" || path === "/") {
+      path = "/index.html";
+    }
+
+    const response = await serveAsset(ctx, component, request, path, {
+      spaFallback,
+      cdnBaseUrl,
+    });
+    if (response) return response;
+
+    if (path === "/index.html") {
+      return new Response(getSetupHtml(), {
+        status: 503,
+        headers: {
+          "Content-Type": "text/html; charset=utf-8",
+          "Cache-Control": "no-store",
+          "Retry-After": "5",
+        },
+      });
+    }
+    return new Response("Not Found", {
+      status: 404,
+      headers: { "Content-Type": "text/plain" },
+    });
+  });
+
+  http.route({
+    pathPrefix: pathPrefix === "/" ? "/" : `${normalizedPrefix}/`,
+    method: "GET",
+    handler: serveStaticFile,
+  });
+
+  if (normalizedPrefix) {
+    http.route({
+      path: normalizedPrefix,
+      method: "GET",
+      handler: serveStaticFile,
+    });
+  }
+}
+
+/**
+ * Serve an uploaded static file from your own HTTP action, or return null when
+ * no file matches so the action can continue with its own routing: server
+ * rendering, prerendered pages, redirects.
+ *
+ * Found files get the same response as `registerStaticRoutes`: content type,
+ * cache headers, ETag revalidation, and legacy CDN redirects. A found file
+ * whose storage can't be read gets a 500 response. A request path with
+ * malformed percent-encoding matches no file, so it returns null.
+ *
+ * The lookup is exact by default. `/` is not mapped to `/index.html`, and there
+ * is no SPA fallback, so the SPA shell never answers for a route your action
+ * handles. To serve the shell, pass `{ path: "/index.html" }`. When your route
+ * has a prefix, pass `path` with the prefix removed.
+ *
+ * @example
+ * ```typescript
+ * // convex/http.ts
+ * const http = httpRouter();
+ * http.route({
+ *   pathPrefix: "/",
+ *   method: "GET",
+ *   handler: httpAction(async (ctx, request) => {
+ *     const file = await serveStaticAsset(ctx, components.hosting, request);
+ *     if (file) return file;
+ *     return await renderPage(request);
+ *   }),
+ * });
+ * export default http;
+ * ```
+ */
+export async function serveStaticAsset(
+  ctx: AssetServingCtx,
+  component: ComponentApi,
+  request: Request,
+  {
+    path,
+    spaFallback = false,
+    cdnBaseUrl,
+  }: {
+    /**
+     * Decoded file path to look up, starting with `/`, such as
+     * `/about/index.html`. Defaults to the decoded request path.
+     */
+    path?: string;
+    /** Serve `/index.html` for a missing path without a file extension. */
+    spaFallback?: boolean;
+    /** Optional custom base URL for convex-fs blob redirects. */
+    cdnBaseUrl?: CdnBaseUrl;
+  } = {},
+): Promise<Response | null> {
+  if (path !== undefined && !path.startsWith("/")) {
+    throw new Error("path must start with /");
+  }
+  const filePath = path ?? decodeRequestPath(new URL(request.url).pathname);
+  if (filePath === null) return null;
+  return await serveAsset(ctx, component, request, filePath, {
+    spaFallback,
+    cdnBaseUrl,
+  });
+}
+
+export { decodeRequestPath };
+
+/**
+ * Serve the uploaded file at `path` (decoded, relative to the mount prefix),
+ * or return null when no file matches. An undefined `spaFallback` uses the
+ * deployment's stored setting.
+ */
+async function serveAsset(
+  ctx: AssetServingCtx,
+  component: ComponentApi,
+  request: Request,
+  path: string,
+  {
+    spaFallback,
+    cdnBaseUrl,
+  }: {
+    spaFallback: boolean | undefined;
+    cdnBaseUrl: CdnBaseUrl | undefined;
+  },
+): Promise<Response | null> {
+  const asset = await ctx.runQuery(component.lib.resolveAssetForHttp, {
+    path,
+    ...(spaFallback === undefined ? {} : { spaFallback }),
+  });
+  if (!asset) return null;
+
+  const contentType = asset.contentType || getMimeType(path);
+  const cacheControl = cacheControlFor(path);
+
+  if (asset.blobId && !isHtmlContentType(contentType)) {
+    const configuredBase = typeof cdnBaseUrl === "function" ? cdnBaseUrl(request) : cdnBaseUrl;
+    const baseUrl = configuredBase ?? `${new URL(request.url).origin}/fs/blobs`;
+    return new Response(null, {
+      status: 302,
+      headers: {
+        Location: `${baseUrl.replace(/\/$/, "")}/${asset.blobId}`,
+        "Cache-Control": cacheControl,
+      },
+    });
+  }
+
+  // TODO(remove in a future major): v1→v2 transitional path. The file still
+  // lives in the app's own storage (a same-name migration inherited the v1
+  // row; see the component's resolveAssetForHttp). Serve it directly from app
+  // storage so the site stays up during migration with no re-upload. Once v1
+  // app-storage assets are no longer supported, delete this branch.
+  if (asset.appStorageId) {
+    if (asset.etag && etagMatches(request.headers.get("If-None-Match"), asset.etag)) {
+      return new Response(null, {
+        status: 304,
+        headers: { ETag: asset.etag, "Cache-Control": cacheControl },
+      });
+    }
+    const blob = await ctx.storage.get(asset.appStorageId as GenericId<"_storage">);
+    if (!blob) {
+      // The component surfaces appStorageId whenever it can't resolve a
+      // storage URL, which also covers a genuinely deleted file (the two are
+      // indistinguishable from the component). If it isn't in app storage
+      // either, treat it as missing, like an empty deployment, rather than
+      // erroring.
+      return null;
+    }
+    return new Response(blob, {
+      status: 200,
+      headers: {
+        "Content-Type": contentType,
+        "Cache-Control": cacheControl,
+        ...(asset.etag ? { ETag: asset.etag } : {}),
+        "X-Content-Type-Options": "nosniff",
+      },
+    });
+  }
+
+  if (!asset.storageUrl) {
+    return new Response("Asset not available", {
+      status: 500,
+      headers: { "Content-Type": "text/plain" },
+    });
+  }
+
+  if (asset.etag && etagMatches(request.headers.get("If-None-Match"), asset.etag)) {
+    return new Response(null, {
+      status: 304,
+      headers: { ETag: asset.etag, "Cache-Control": cacheControl },
+    });
+  }
+
+  const storageResponse = await fetch(asset.storageUrl);
+  if (!storageResponse.ok || !storageResponse.body) {
+    return new Response("Storage error", {
+      status: 500,
+      headers: { "Content-Type": "text/plain" },
+    });
+  }
+
+  return new Response(storageResponse.body, {
+    status: 200,
+    headers: {
+      "Content-Type": contentType,
+      "Cache-Control": cacheControl,
+      ...(asset.etag ? { ETag: asset.etag } : {}),
+      "X-Content-Type-Options": "nosniff",
+    },
+  });
+}
+
+/**
+ * Expose a query that clients can subscribe to for live reload on deploy.
+ * This is only needed if you use `UpdateBanner` / `useDeploymentUpdates` from
+ * `@samebase/convex-hosting/react`. If you don't surface deployment updates
+ * in your app, you don't need to call this.
+ *
+ * @example
+ * ```typescript
+ * // convex/hosting.ts
+ * import { exposeDeploymentQuery } from "@samebase/convex-hosting";
+ * import { components } from "./_generated/api";
+ *
+ * export const { getCurrentDeployment } = exposeDeploymentQuery(
+ *   components.hosting,
+ * );
+ * ```
+ */
+export function exposeDeploymentQuery(component: ComponentApi) {
+  return {
+    getCurrentDeployment: queryGeneric({
+      args: {},
+      returns: v.union(deploymentInfoValidator, v.null()),
+      handler: async (ctx) => {
+        const deployment = await ctx.runQuery(component.lib.getCurrentDeployment, {});
+        if (!deployment) return null;
+        // Cleanup accounting is private component state. Returning it through
+        // this public wrapper would fail the narrower response validator.
+        const deploymentWithCleanup = deployment as typeof deployment & {
+          pendingBlobCleanupCount?: number;
+        };
+        const { pendingBlobCleanupCount: _pending, ...publicDeployment } = deploymentWithCleanup;
+        return publicDeployment;
+      },
+    }),
+  };
+}
+
+/**
+ * Derive the Convex cloud URL from a `.convex.site` hostname.
+ * Useful when your frontend is served by this component and needs
+ * to connect to its own Convex backend without an explicit env var.
+ *
+ * @example
+ * ```typescript
+ * import { getConvexUrl } from "@samebase/convex-hosting";
+ *
+ * const convexUrl = import.meta.env.VITE_CONVEX_URL ?? getConvexUrl();
+ * const convex = new ConvexReactClient(convexUrl);
+ * ```
+ */
+export function getConvexUrl(): string {
+  if (typeof window === "undefined") {
+    throw new Error("getConvexUrl() can only be called in a browser context");
+  }
+  if (window.location.hostname.endsWith(".convex.site")) {
+    return `https://${window.location.hostname.replace(".convex.site", ".convex.cloud")}`;
+  }
+  throw new Error("Unable to derive Convex URL. Please set VITE_CONVEX_URL environment variable.");
+}

package/src/client/setup.test.ts

@@ -0,0 +1,22 @@
+/// <reference types="vite/client" />
+import { test } from "vite-plus/test";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+import { defineSchema, type GenericSchema, type SchemaDefinition } from "convex/server";
+import { type ComponentApi } from "../component/_generated/component.js";
+import { componentsGeneric } from "convex/server";
+import { register } from "../test.js";
+
+export function initConvexTest<Schema extends SchemaDefinition<GenericSchema, boolean>>(
+  schema?: Schema,
+) {
+  const t = convexTest(schema ?? defineSchema({}), modules);
+  register(t);
+  return t;
+}
+export const components = componentsGeneric() as unknown as {
+  hosting: ComponentApi;
+};
+
+test("setup", () => {});

package/src/component/_generated/api.ts

@@ -0,0 +1,54 @@
+/* eslint-disable */
+/**
+ * Generated `api` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type * as http from "../http.js";
+import type * as lib from "../lib.js";
+import type * as serving from "../serving.js";
+
+import type {
+  ApiFromModules,
+  FilterApi,
+  FunctionReference,
+} from "convex/server";
+import { anyApi, componentsGeneric } from "convex/server";
+
+const fullApi: ApiFromModules<{
+  http: typeof http;
+  lib: typeof lib;
+  serving: typeof serving;
+}> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's public API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = api.myModule.myFunction;
+ * ```
+ */
+export const api: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "public">
+> = anyApi as any;
+
+/**
+ * A utility for referencing Convex functions in your app's internal API.
+ *
+ * Usage:
+ * ```js
+ * const myFunctionReference = internal.myModule.myFunction;
+ * ```
+ */
+export const internal: FilterApi<
+  typeof fullApi,
+  FunctionReference<any, "internal">
+> = anyApi as any;
+
+export const components = componentsGeneric() as unknown as {};

package/src/component/_generated/component.ts

@@ -0,0 +1,55 @@
+/* eslint-disable */
+/**
+ * Generated `ComponentApi` utility.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type { FunctionReference } from "convex/server";
+
+/**
+ * A utility for referencing a Convex component's exposed API.
+ *
+ * Useful when expecting a parameter like `components.myComponent`.
+ * Usage:
+ * ```ts
+ * async function myFunction(ctx: QueryCtx, component: ComponentApi) {
+ *   return ctx.runQuery(component.someFile.someQuery, { ...args });
+ * }
+ * ```
+ */
+export type ComponentApi<Name extends string | undefined = string | undefined> =
+  {
+    lib: {
+      getCurrentDeployment: FunctionReference<
+        "query",
+        "internal",
+        {},
+        {
+          _creationTime: number;
+          _id: string;
+          currentDeploymentId: string;
+          deployedAt: number;
+          pendingBlobCleanupCount?: number;
+          spaFallback?: boolean;
+        } | null,
+        Name
+      >;
+      resolveAssetForHttp: FunctionReference<
+        "query",
+        "internal",
+        { path: string; spaFallback?: boolean },
+        {
+          appStorageId?: string;
+          blobId?: string;
+          contentType: string;
+          etag?: string;
+          storageUrl?: string;
+        } | null,
+        Name
+      >;
+    };
+  };

package/src/component/_generated/dataModel.ts

@@ -0,0 +1,60 @@
+/* eslint-disable */
+/**
+ * Generated data model types.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  DataModelFromSchemaDefinition,
+  DocumentByName,
+  TableNamesInDataModel,
+  SystemTableNames,
+} from "convex/server";
+import type { GenericId } from "convex/values";
+import schema from "../schema.js";
+
+/**
+ * The names of all of your Convex tables.
+ */
+export type TableNames = TableNamesInDataModel<DataModel>;
+
+/**
+ * The type of a document stored in Convex.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Doc<TableName extends TableNames> = DocumentByName<
+  DataModel,
+  TableName
+>;
+
+/**
+ * An identifier for a document in Convex.
+ *
+ * Convex documents are uniquely identified by their `Id`, which is accessible
+ * on the `_id` field. To learn more, see [Document IDs](https://docs.convex.dev/using/document-ids).
+ *
+ * Documents can be loaded using `db.get(tableName, id)` in query and mutation functions.
+ *
+ * IDs are just strings at runtime, but this type can be used to distinguish them from other
+ * strings when type checking.
+ *
+ * @typeParam TableName - A string literal type of the table name (like "users").
+ */
+export type Id<TableName extends TableNames | SystemTableNames> =
+  GenericId<TableName>;
+
+/**
+ * A type describing your Convex data model.
+ *
+ * This type includes information about what tables you have, the type of
+ * documents stored in those tables, and the indexes defined on them.
+ *
+ * This type is used to parameterize methods like `queryGeneric` and
+ * `mutationGeneric` to make them type-safe.
+ */
+export type DataModel = DataModelFromSchemaDefinition<typeof schema>;

package/src/component/_generated/server.ts

@@ -0,0 +1,156 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+
+import type {
+  ActionBuilder,
+  HttpActionBuilder,
+  MutationBuilder,
+  QueryBuilder,
+  GenericActionCtx,
+  GenericMutationCtx,
+  GenericQueryCtx,
+  GenericDatabaseReader,
+  GenericDatabaseWriter,
+} from "convex/server";
+import {
+  actionGeneric,
+  httpActionGeneric,
+  queryGeneric,
+  mutationGeneric,
+  internalActionGeneric,
+  internalMutationGeneric,
+  internalQueryGeneric,
+} from "convex/server";
+import type { DataModel } from "./dataModel.js";
+
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query: QueryBuilder<DataModel, "public"> = queryGeneric;
+
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery: QueryBuilder<DataModel, "internal"> =
+  internalQueryGeneric;
+
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation: MutationBuilder<DataModel, "public"> = mutationGeneric;
+
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation: MutationBuilder<DataModel, "internal"> =
+  internalMutationGeneric;
+
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action: ActionBuilder<DataModel, "public"> = actionGeneric;
+
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction: ActionBuilder<DataModel, "internal"> =
+  internalActionGeneric;
+
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction: HttpActionBuilder = httpActionGeneric;
+
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;