@samebase/convex-hosting 0.3.2 → 0.4.1

package/src/client/index.ts

@@ -1,344 +0,0 @@
-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,
-  errorResponse,
-  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 errorResponse(400, "Bad Request");
-    }
-    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 errorResponse(404, "Not Found");
-  });
-
-  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 errorResponse(500, "Asset not available");
-  }
-
-  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 errorResponse(500, "Storage error");
-  }
-
-  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

@@ -1,22 +0,0 @@
-/// <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

@@ -1,54 +0,0 @@
-/* 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

@@ -1,55 +0,0 @@
-/* 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

@@ -1,60 +0,0 @@
-/* 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

@@ -1,156 +0,0 @@
-/* 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>;

package/src/component/convex.config.ts

@@ -1,3 +0,0 @@
-import { defineComponent } from "convex/server";
-
-export default defineComponent("hosting");