@samebase/convex-hosting 0.0.0-stage → 0.3.1

package/src/component/schema.ts

@@ -0,0 +1,75 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+  staticAssets: defineTable({
+    path: v.string(), // URL path, e.g., "/index.html", "/assets/main-abc123.js"
+    storageId: v.optional(v.id("_storage")), // Reference to Convex file storage (used for HTML + non-CDN assets)
+    blobId: v.optional(v.string()), // convex-fs blob ID (used for CDN-served assets)
+    contentType: v.string(), // MIME type, e.g., "text/html; charset=utf-8"
+    deploymentId: v.string(), // UUID for garbage collection
+  })
+    .index("by_path", ["path"])
+    .index("by_deploymentId", ["deploymentId"])
+    .index("by_storageId", ["storageId"]),
+
+  // Publication moves replaced storage files here. Missing non-HTML paths with
+  // an extension can still resolve to these files. A later upload removes them
+  // after expiresAt, at least seven days after replacement.
+  retiredAssets: defineTable({
+    path: v.string(),
+    storageId: v.id("_storage"),
+    contentType: v.string(),
+    deploymentId: v.string(),
+    expiresAt: v.number(),
+  })
+    .index("by_path", ["path"])
+    .index("by_storageId", ["storageId"])
+    .index("by_expiresAt", ["expiresAt"]),
+
+  // Uploads stage their manifest in small chunks because the Convex CLI takes
+  // function arguments on the command line. Only publishDeployment copies a
+  // complete staged manifest into staticAssets, so partial uploads are never
+  // visible to HTTP requests.
+  stagedAssets: defineTable({
+    path: v.string(),
+    storageId: v.optional(v.id("_storage")),
+    blobId: v.optional(v.string()),
+    contentType: v.string(),
+    deploymentId: v.string(),
+  })
+    .index("by_deploymentId", ["deploymentId"])
+    .index("by_storageId", ["storageId"]),
+
+  // Old ConvexFS blobs are app-owned, so the component cannot delete them.
+  // Persist the IDs until the CLI's app-level delete function succeeds. This
+  // also makes cleanup recoverable when a publish response is lost.
+  pendingBlobCleanup: defineTable({
+    blobId: v.string(),
+  }).index("by_blobId", ["blobId"]),
+
+  // Storage IDs from the previous live manifest are queued by the atomic
+  // publish, then deleted in bounded follow-up mutations. This avoids both a
+  // large publish transaction and races with unrelated concurrent uploads.
+  pendingStorageCleanup: defineTable({
+    storageId: v.id("_storage"),
+  }).index("by_storageId", ["storageId"]),
+
+  // Cleanup may be queued before the first successful deployment exists, so
+  // its count cannot live only on deploymentInfo.
+  cleanupState: defineTable({
+    pendingBlobCleanupCount: v.number(),
+  }),
+
+  // Singleton table to track the current deployment
+  // Clients subscribe to this to know when to reload
+  deploymentInfo: defineTable({
+    currentDeploymentId: v.string(),
+    deployedAt: v.number(), // timestamp
+    // SPA fallback config for the current deployment. Set at upload time
+    // (`--no-spa` turns it off). Absent means enabled. Travels with the
+    // deploy so the serving behavior matches the code that was shipped.
+    spaFallback: v.optional(v.boolean()),
+    pendingBlobCleanupCount: v.optional(v.number()),
+  }),
+});

package/src/component/serving.ts

@@ -0,0 +1,158 @@
+// Pure, dependency-free helpers shared by the HTTP handler (http.ts) and the
+// asset-resolution query (lib.ts). Kept separate so lib.ts can reuse them
+// without importing the HTTP router.
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".mjs": "application/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".txt": "text/plain; charset=utf-8",
+  ".map": "application/json",
+  ".webmanifest": "application/manifest+json",
+  ".xml": "application/xml",
+};
+
+export function getSetupHtml(): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Convex Hosting</title>
+  <style>
+    * { box-sizing: border-box; }
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+      max-width: 640px;
+      margin: 0 auto;
+      padding: 40px 20px;
+      background: #fafafa;
+      color: #333;
+      line-height: 1.6;
+    }
+    h1 { color: #111; margin-bottom: 8px; }
+    .subtitle { color: #666; margin-bottom: 32px; }
+    code {
+      background: #e8e8e8;
+      padding: 2px 6px;
+      border-radius: 4px;
+      font-size: 14px;
+    }
+    pre {
+      background: #1a1a1a;
+      color: #f0f0f0;
+      padding: 16px;
+      border-radius: 8px;
+      overflow-x: auto;
+      font-size: 14px;
+    }
+    .step { margin-bottom: 24px; }
+    .step-num {
+      display: inline-block;
+      background: #333;
+      color: white;
+      width: 24px;
+      height: 24px;
+      border-radius: 50%;
+      text-align: center;
+      font-size: 14px;
+      line-height: 24px;
+      margin-right: 8px;
+    }
+    a { color: #0070f3; }
+  </style>
+</head>
+<body>
+  <h1>Almost there!</h1>
+  <p class="subtitle">Your Convex backend is running, but no static files have been deployed yet.</p>
+
+  <div class="step">
+    <span class="step-num">1</span>
+    <strong>Build your frontend</strong>
+    <pre>npm run build</pre>
+  </div>
+
+  <div class="step">
+    <span class="step-num">2</span>
+    <strong>Deploy your static files</strong>
+    <pre>npx @samebase/convex-hosting deploy</pre>
+  </div>
+
+  <p>Or deploy everything in one command:</p>
+  <pre>npm run deploy</pre>
+
+  <p style="margin-top: 32px; color: #666; font-size: 14px;">
+    Learn more at <a href="https://github.com/samebase/convex-hosting">github.com/samebase/convex-hosting</a>
+  </p>
+</body>
+</html>`;
+}
+
+export function getMimeType(path: string): string {
+  const ext = path.substring(path.lastIndexOf(".")).toLowerCase();
+  return MIME_TYPES[ext] || "application/octet-stream";
+}
+
+export function hasFileExtension(path: string): boolean {
+  const lastSegment = path.split("/").pop() || "";
+  return lastSegment.includes(".") && !lastSegment.startsWith(".");
+}
+
+// Bundler content-hash suffix: e.g. `index-lj_vq_aF.js`,
+// `index-D3LP-ukt.js`, or `style-B71cUw87.css`. Requiring at least one
+// non-letter avoids treating ordinary names such as `privacy-policy.html` as
+// content-addressed assets.
+export function isHashedAsset(path: string): boolean {
+  const match = path.match(/[-.]([\dA-Za-z_-]{6,32})\.[A-Za-z\d]+$/);
+  return match !== null && /[\d_-]/.test(match[1]);
+}
+
+export function isHtmlContentType(contentType: string): boolean {
+  return contentType.startsWith("text/html");
+}
+
+export function cacheControlFor(path: string): string {
+  return !path.toLowerCase().endsWith(".html") && isHashedAsset(path)
+    ? "public, max-age=31536000, immutable"
+    : "public, max-age=0, must-revalidate";
+}
+
+/**
+ * Decode the URL pathname before looking it up in the asset table. A malformed
+ * escape sequence is a bad request, not a missing static asset.
+ */
+export function decodeRequestPath(pathname: string): string | null {
+  try {
+    return decodeURIComponent(pathname);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * If-None-Match uses weak comparison for GET and HEAD requests. Browsers and
+ * proxies may send a weak validator or a comma-separated list of validators.
+ */
+export function etagMatches(ifNoneMatch: string | null, currentEtag: string): boolean {
+  if (!ifNoneMatch) return false;
+
+  const normalize = (value: string) => value.trim().replace(/^W\//, "").trim();
+  const normalizedCurrent = normalize(currentEtag);
+
+  return ifNoneMatch.split(",").some((candidate) => {
+    const normalizedCandidate = normalize(candidate);
+    return normalizedCandidate === "*" || normalizedCandidate === normalizedCurrent;
+  });
+}

package/src/component/setup.test.ts

@@ -0,0 +1,11 @@
+/// <reference types="vite/client" />
+import { test } from "vite-plus/test";
+import schema from "./schema.js";
+import { convexTest } from "convex-test";
+export const modules = import.meta.glob("./**/*.*s");
+
+export function initConvexTest() {
+  const t = convexTest(schema, modules);
+  return t;
+}
+test("setup", () => {});

package/src/react/index.tsx

@@ -0,0 +1,197 @@
+"use client";
+
+import { useQuery_experimental } from "convex/react";
+import { useState, useMemo, type CSSProperties, type JSX } from "react";
+import { makeFunctionReference, type FunctionReference } from "convex/server";
+
+type DeploymentInfo = {
+  _id: string;
+  _creationTime: number;
+  currentDeploymentId: string;
+  deployedAt: number;
+  spaFallback?: boolean;
+} | null;
+
+type DeploymentQueryRef = FunctionReference<
+  "query",
+  "public",
+  Record<string, never>,
+  DeploymentInfo
+>;
+
+const DEFAULT_QUERY_REF = makeFunctionReference<"query", Record<string, never>, DeploymentInfo>(
+  "hosting:getCurrentDeployment",
+) as DeploymentQueryRef;
+
+/* eslint-disable react-refresh/only-export-components */
+
+/**
+ * Hook to detect when a new deployment is available.
+ *
+ * @param getCurrentDeployment - Optional query reference. Defaults to
+ *   `api.hosting.getCurrentDeployment` (resolved by path). If you've
+ *   re-exported the deployment query under a different module name, pass the
+ *   reference explicitly.
+ *
+ * @example
+ * ```tsx
+ * import { useDeploymentUpdates } from "@samebase/convex-hosting/react";
+ *
+ * function App() {
+ *   const { updateAvailable, reload } = useDeploymentUpdates();
+ *   return updateAvailable ? <button onClick={reload}>Reload</button> : null;
+ * }
+ * ```
+ */
+export function useDeploymentUpdates(getCurrentDeployment?: DeploymentQueryRef) {
+  const result = useQuery_experimental({
+    query: getCurrentDeployment ?? DEFAULT_QUERY_REF,
+    args: {},
+  });
+
+  const deployment = result.status === "success" ? result.data : null;
+  const setupError =
+    result.status === "error" ? deploymentQuerySetupHelp(getCurrentDeployment) : null;
+
+  const [initialDeploymentId, setInitialDeploymentId] = useState<string | null>(null);
+  const [dismissedDeploymentId, setDismissedDeploymentId] = useState<string | null>(null);
+
+  if (deployment && initialDeploymentId === null) {
+    setInitialDeploymentId(deployment.currentDeploymentId);
+  }
+
+  const updateAvailable = useMemo(() => {
+    if (!deployment || initialDeploymentId === null) return false;
+    const hasNew = deployment.currentDeploymentId !== initialDeploymentId;
+    const isDismissed = deployment.currentDeploymentId === dismissedDeploymentId;
+    return hasNew && !isDismissed;
+  }, [deployment, initialDeploymentId, dismissedDeploymentId]);
+
+  const reload = () => {
+    window.location.reload();
+  };
+
+  const dismiss = () => {
+    if (deployment) {
+      setDismissedDeploymentId(deployment.currentDeploymentId);
+    }
+  };
+
+  return {
+    updateAvailable,
+    reload,
+    dismiss,
+    deployment,
+    /**
+     * When set, the deployment query isn't exported from the app; the banner
+     * won't work until the user wires it up. The string is suitable to render
+     * during local development so the missing setup is obvious.
+     */
+    setupError,
+  };
+}
+
+function deploymentQuerySetupHelp(ref: DeploymentQueryRef | undefined): string {
+  if (ref) {
+    return "Deployment query failed. Verify the function you passed to useDeploymentUpdates is deployed.";
+  }
+  return [
+    "@samebase/convex-hosting: UpdateBanner requires you to expose the deployment query.",
+    "Create convex/hosting.ts:",
+    "",
+    '  import { exposeDeploymentQuery } from "@samebase/convex-hosting";',
+    '  import { components } from "./_generated/api";',
+    "  export const { getCurrentDeployment } = exposeDeploymentQuery(",
+    "    components.hosting,",
+    "  );",
+  ].join("\n");
+}
+
+/**
+ * Ready-to-use banner shown when a new deployment is available.
+ *
+ * @example
+ * ```tsx
+ * import { UpdateBanner } from "@samebase/convex-hosting/react";
+ * <UpdateBanner />
+ * ```
+ */
+export function UpdateBanner({
+  getCurrentDeployment,
+  message = "A new version is available!",
+  buttonText = "Reload",
+  dismissable = true,
+  className,
+  style,
+}: {
+  getCurrentDeployment?: DeploymentQueryRef;
+  message?: string;
+  buttonText?: string;
+  dismissable?: boolean;
+  className?: string;
+  style?: CSSProperties;
+} = {}): JSX.Element | null {
+  const { updateAvailable, reload, dismiss, setupError } =
+    useDeploymentUpdates(getCurrentDeployment);
+
+  if (setupError) {
+    if (typeof console !== "undefined") {
+      console.warn(setupError);
+    }
+    return null;
+  }
+
+  if (!updateAvailable) return null;
+
+  const defaultStyle: CSSProperties = {
+    position: "fixed",
+    bottom: "1rem",
+    right: "1rem",
+    backgroundColor: "#1a1a2e",
+    color: "#fff",
+    padding: "1rem 1.5rem",
+    borderRadius: "8px",
+    boxShadow: "0 4px 12px rgba(0, 0, 0, 0.3)",
+    display: "flex",
+    alignItems: "center",
+    gap: "1rem",
+    zIndex: 9999,
+    fontFamily: "system-ui, -apple-system, sans-serif",
+    fontSize: "14px",
+    ...style,
+  };
+
+  const buttonStyle: CSSProperties = {
+    backgroundColor: "#4f46e5",
+    color: "#fff",
+    border: "none",
+    padding: "0.5rem 1rem",
+    borderRadius: "4px",
+    cursor: "pointer",
+    fontWeight: 500,
+  };
+
+  const dismissStyle: CSSProperties = {
+    background: "none",
+    border: "none",
+    color: "#888",
+    cursor: "pointer",
+    padding: "0.25rem",
+    fontSize: "18px",
+    lineHeight: 1,
+  };
+
+  return (
+    <div className={className} style={defaultStyle}>
+      <span>{message}</span>
+      <button onClick={reload} style={buttonStyle}>
+        {buttonText}
+      </button>
+      {dismissable && (
+        <button onClick={dismiss} style={dismissStyle} aria-label="Dismiss">
+          ×
+        </button>
+      )}
+    </div>
+  );
+}

package/src/test.ts

@@ -0,0 +1,23 @@
+/// <reference types="vite/client" />
+import type { TestConvex } from "convex-test";
+import type { GenericSchema, SchemaDefinition } from "convex/server";
+import { componentsGeneric } from "convex/server";
+import type { ComponentApi } from "./component/_generated/component.js";
+import schema from "./component/schema.js";
+const modules = import.meta.glob("./component/**/*.ts");
+
+/**
+ * Register the component with the test convex instance.
+ * @param t - The test convex instance, e.g. from calling `convexTest`.
+ * @param name - The name of the component, as registered in convex.config.ts.
+ * @returns a component api to test via ctx.runMutation or for thick client
+ *   usage. Also provides types for convex-test's defineTestApp.
+ */
+export function register(
+  t: TestConvex<SchemaDefinition<GenericSchema, boolean>>,
+  name: string = "hosting",
+) {
+  t.registerComponent(name, schema, modules);
+  return componentsGeneric()[name] as unknown as ComponentApi;
+}
+export default { register, schema, modules };