@openlup/platform 0.0.0-stage → 0.15.0

package/src/blob/s3.ts

@@ -0,0 +1,87 @@
+// S3-compatible adapter for the platform-runtime BlobStoragePort.
+//
+// Targets any S3-compatible object store (AWS S3, MinIO, R2, Spaces) used by a self-hosted
+// node-postgres bundle. To stay credential-free in CI and avoid pulling a new SDK dependency
+// into this wave, it depends on a minimal STRUCTURAL client interface (PutObject/HeadObject/
+// DeleteObject/ListObjectsV2). A thin factory over `@aws-sdk/client-s3` satisfies this shape;
+// tests inject a fake. URLs are derived from a configurable public base (CDN or path-style).
+
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+
+export interface S3ObjectClient {
+  putObject(input: {
+    Bucket: string;
+    Key: string;
+    Body: Uint8Array | Buffer;
+    ContentType?: string;
+  }): Promise<unknown>;
+  headObject(input: { Bucket: string; Key: string }): Promise<unknown>;
+  deleteObject(input: { Bucket: string; Key: string }): Promise<unknown>;
+  listObjectsV2(input: {
+    Bucket: string;
+    Prefix?: string;
+  }): Promise<{ Contents?: Array<{ Key?: string }> }>;
+}
+
+export interface S3BlobOptions {
+  bucket: string;
+  /** Public base URL for objects, e.g. https://cdn.example.com or https://s3.region.amazonaws.com/bucket. */
+  baseUrl: string;
+  defaultContentType?: string;
+}
+
+export function createS3BlobStorage(client: S3ObjectClient, options: S3BlobOptions): BlobStoragePort {
+  const bucket = options.bucket;
+  const baseUrl = options.baseUrl.replace(/\/$/, "");
+  const defaultContentType = options.defaultContentType ?? "application/octet-stream";
+
+  return {
+    urlFor(key: string): string {
+      return `${baseUrl}/${normalizeKey(key)}`;
+    },
+
+    async upload(key, data, opts) {
+      const objectKey = normalizeKey(key);
+      await client.putObject({
+        Bucket: bucket,
+        Key: objectKey,
+        Body: data,
+        ContentType: opts?.contentType ?? defaultContentType,
+      });
+      return { url: this.urlFor(objectKey), pathname: objectKey };
+    },
+
+    async exists(key) {
+      try {
+        await client.headObject({ Bucket: bucket, Key: normalizeKey(key) });
+        return true;
+      } catch {
+        return false;
+      }
+    },
+
+    async delete(keyOrUrl) {
+      await client.deleteObject({ Bucket: bucket, Key: stripBaseUrl(keyOrUrl, baseUrl) });
+    },
+
+    async list(prefix) {
+      const result = await client.listObjectsV2({
+        Bucket: bucket,
+        Prefix: prefix ? normalizeKey(prefix) : undefined,
+      });
+      const keys = (result.Contents ?? [])
+        .map((entry) => entry.Key)
+        .filter((key): key is string => typeof key === "string")
+        .sort();
+      return { keys };
+    },
+  };
+}
+
+function normalizeKey(key: string): string {
+  return key.replace(/^\/+/, "");
+}
+
+function stripBaseUrl(keyOrUrl: string, baseUrl: string): string {
+  return keyOrUrl.startsWith(`${baseUrl}/`) ? normalizeKey(keyOrUrl.slice(baseUrl.length + 1)) : normalizeKey(keyOrUrl);
+}

package/src/blob/s3Client.ts

@@ -0,0 +1,91 @@
+// Default S3 client for the S3-compatible blob capability, built from the environment.
+//
+// `@aws-sdk/client-s3` is an optional peer: it is loaded on the first storage call, through Node's
+// own module resolution, so an application that never selects S3 needs neither the SDK nor its
+// settings. Settings:
+// BLOB_S3_REGION (default us-east-1), BLOB_S3_ENDPOINT (an S3-compatible service; path-style
+// addressing follows from BLOB_S3_FORCE_PATH_STYLE=true), and BLOB_S3_ACCESS_KEY_ID with
+// BLOB_S3_SECRET_ACCESS_KEY (both, or neither to use the SDK's default credential chain).
+
+import { createRequire } from "node:module";
+
+import type { S3ObjectClient } from "./s3.js";
+
+type Env = Record<string, string | undefined>;
+export interface S3Sdk {
+  S3Client: new (config: {
+    region: string;
+    endpoint?: string;
+    forcePathStyle: boolean;
+    credentials?: { accessKeyId: string; secretAccessKey: string };
+  }) => { send(command: unknown): ReturnType<S3ObjectClient["listObjectsV2"]> };
+  PutObjectCommand: new (input: Parameters<S3ObjectClient["putObject"]>[0]) => unknown;
+  HeadObjectCommand: new (input: Parameters<S3ObjectClient["headObject"]>[0]) => unknown;
+  DeleteObjectCommand: new (input: Parameters<S3ObjectClient["deleteObject"]>[0]) => unknown;
+  ListObjectsV2Command: new (input: Parameters<S3ObjectClient["listObjectsV2"]>[0]) => unknown;
+}
+
+function setting(env: Env, name: string): string | undefined {
+  const value = env[name]?.trim();
+  return value ? value : undefined;
+}
+
+function loadS3Sdk(): S3Sdk {
+  return createRequire(import.meta.url)("@aws-sdk/client-s3") as S3Sdk;
+}
+
+/**
+ * Build an `S3ObjectClient` whose SDK client is created lazily from the given environment.
+ * `loadSdk` replaces the SDK loader (tests).
+ */
+export function createS3ClientFromEnv(env: Env, loadSdk: () => S3Sdk = loadS3Sdk): S3ObjectClient {
+  const accessKeyId = setting(env, "BLOB_S3_ACCESS_KEY_ID");
+  const secretAccessKey = setting(env, "BLOB_S3_SECRET_ACCESS_KEY");
+  if ((accessKeyId === undefined) !== (secretAccessKey === undefined)) {
+    throw new Error("blob_s3_credentials_incomplete");
+  }
+  let loaded: { sdk: S3Sdk; client: InstanceType<S3Sdk["S3Client"]> } | null = null;
+  const connect = async () => {
+    if (loaded) return loaded;
+    let sdk: S3Sdk;
+    try { sdk = loadSdk(); } catch (cause) { peerMissing(cause); }
+    loaded = {
+      sdk,
+      client: new sdk.S3Client({
+        region: setting(env, "BLOB_S3_REGION") ?? "us-east-1",
+        endpoint: setting(env, "BLOB_S3_ENDPOINT"),
+        forcePathStyle: setting(env, "BLOB_S3_FORCE_PATH_STYLE") === "true",
+        credentials: accessKeyId && secretAccessKey ? { accessKeyId, secretAccessKey } : undefined,
+      }),
+    };
+    return loaded;
+  };
+  return {
+    async putObject(input) {
+      const { sdk, client } = await connect();
+      return client.send(new sdk.PutObjectCommand(input));
+    },
+    async headObject(input) {
+      const { sdk, client } = await connect();
+      return client.send(new sdk.HeadObjectCommand(input));
+    },
+    async deleteObject(input) {
+      const { sdk, client } = await connect();
+      return client.send(new sdk.DeleteObjectCommand(input));
+    },
+    async listObjectsV2(input) {
+      const { sdk, client } = await connect();
+      return client.send(new sdk.ListObjectsV2Command(input));
+    },
+  };
+}
+
+/** Translate only absence of this optional peer; preserve broken SDKs and other failures. */
+function peerMissing(cause: unknown): never {
+  if (cause instanceof Error && "code" in cause
+    && (cause.code === "ERR_MODULE_NOT_FOUND" || cause.code === "MODULE_NOT_FOUND")
+    && /^Cannot find (?:package|module) ['"]@aws-sdk\/client-s3['"]/.test(cause.message)) {
+    throw new Error("OPENLUP_E_PEER_MISSING: @aws-sdk/client-s3 is required by the S3 blob capability; install it alongside @openlup/platform", { cause });
+  }
+  throw cause;
+}

package/src/blob/supabase.ts

@@ -0,0 +1,88 @@
+// Supabase Storage adapter for the platform-runtime BlobStoragePort.
+//
+// Wraps `client.storage.from(bucket)` 1:1 with the existing application storage usage:
+// upsert uploads, public-URL resolution via getPublicUrl, and bucket-scoped list/remove. Keys
+// are bucket-relative paths. Behavior matches the current inline storage calls so the default
+// vercel-supabase bundle (which uses this for storage buckets) is byte-identical.
+
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+
+/** Minimal structural shape of the Supabase Storage bucket API we depend on. */
+export interface SupabaseStorageBucket {
+  upload(
+    path: string,
+    bytes: Uint8Array | Buffer,
+    options?: { contentType?: string; upsert?: boolean },
+  ): PromiseLike<{ data: unknown; error: { message?: string } | null }>;
+  remove(paths: string[]): PromiseLike<{ data: unknown; error: { message?: string } | null }>;
+  list(
+    prefix?: string,
+  ): PromiseLike<{ data: Array<{ name: string }> | null; error: { message?: string } | null }>;
+  getPublicUrl(path: string): { data: { publicUrl: string } };
+}
+
+export interface SupabaseStorageClient {
+  storage: { from(bucket: string): SupabaseStorageBucket };
+}
+
+export function createSupabaseBlobStorage(
+  client: SupabaseStorageClient,
+  bucket: string,
+  options: { defaultContentType?: string } = {},
+): BlobStoragePort {
+  const from = (): SupabaseStorageBucket => client.storage.from(bucket);
+  const defaultContentType = options.defaultContentType ?? "application/octet-stream";
+
+  return {
+    urlFor(key: string): string {
+      return from().getPublicUrl(key).data.publicUrl;
+    },
+
+    async upload(key, data, opts) {
+      const bucketApi = from();
+      const result = await bucketApi.upload(key, data, {
+        contentType: opts?.contentType ?? defaultContentType,
+        upsert: true,
+      });
+      if (result.error) {
+        throw new Error(`supabase_storage_upload_failed:${result.error.message ?? "unknown"}`);
+      }
+      return { url: bucketApi.getPublicUrl(key).data.publicUrl, pathname: key };
+    },
+
+    async exists(key) {
+      // Supabase has no head(); list the parent folder and match the leaf name.
+      const slash = key.lastIndexOf("/");
+      const folder = slash >= 0 ? key.slice(0, slash) : "";
+      const leaf = slash >= 0 ? key.slice(slash + 1) : key;
+      const result = await from().list(folder || undefined);
+      if (result.error) return false;
+      return (result.data ?? []).some((entry) => entry.name === leaf);
+    },
+
+    async delete(keyOrUrl) {
+      const result = await from().remove([toBucketKey(keyOrUrl, bucket)]);
+      if (result.error) {
+        throw new Error(`supabase_storage_remove_failed:${result.error.message ?? "unknown"}`);
+      }
+    },
+
+    async list(prefix) {
+      const result = await from().list(prefix);
+      if (result.error) {
+        throw new Error(`supabase_storage_list_failed:${result.error.message ?? "unknown"}`);
+      }
+      const base = prefix ? `${prefix.replace(/\/$/, "")}/` : "";
+      return { keys: (result.data ?? []).map((entry) => `${base}${entry.name}`) };
+    },
+  };
+}
+
+// Accept either a bucket-relative key or a full public URL; strip everything up to and
+// including the bucket segment so remove() always gets a bucket-relative path.
+function toBucketKey(keyOrUrl: string, bucket: string): string {
+  const marker = `/storage/v1/object/public/${bucket}/`;
+  const idx = keyOrUrl.indexOf(marker);
+  if (idx >= 0) return keyOrUrl.slice(idx + marker.length);
+  return keyOrUrl;
+}

package/src/blob/vercel.ts

@@ -0,0 +1,127 @@
+// Vercel Blob adapter for the platform-runtime BlobStoragePort.
+//
+// Wraps the CURRENT `@vercel/blob` behavior 1:1 so the default vercel-supabase bundle is
+// byte-identical: public access, image content-type pass-through, no random suffix, the same
+// 30-day cache-control, O(1) head() existence checks, and the deterministic public CDN URL
+// derived from the store id encoded in BLOB_READ_WRITE_TOKEN. Operates on FULL keys
+// (pathnames); any key prefix or suffix stays in the consuming facade.
+
+import type { BlobStoragePort } from "@openlup/core/platform-runtime";
+
+/**
+ * The `@vercel/blob` functions this adapter calls, supplied by the application (pass the module
+ * itself). The SDK reads its own credentials from the environment, as before.
+ */
+export interface VercelBlobSdk {
+  put(
+    pathname: string,
+    body: Buffer,
+    options: { access: "public"; contentType: string; addRandomSuffix: boolean; cacheControlMaxAge: number },
+  ): Promise<{ url: string; pathname: string }>;
+  head(url: string): Promise<{ url?: string } | null | undefined>;
+  del(url: string): Promise<unknown>;
+  list(options: { prefix?: string }): Promise<{ blobs: Array<{ pathname: string; url: string; uploadedAt: Date }> }>;
+}
+
+const DEFAULT_CACHE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30; // 30 days
+
+export interface VercelBlobAdapterOptions {
+  /** The `@vercel/blob` module. */
+  sdk: VercelBlobSdk;
+  /** Environment whose BLOB_READ_WRITE_TOKEN is read at each call when `token` is absent. */
+  env: Record<string, string | undefined>;
+  /**
+   * Explicit token for deriving the public store URL (`urlFor`, `exists`); takes precedence over
+   * `env`. Upload, list and delete use the credentials the injected SDK reads itself, so `env` and
+   * `token` must name the same store as the SDK's own configuration.
+   */
+  token?: string;
+  /** Default content-type when an upload omits one (image/png when absent). */
+  defaultContentType?: string;
+  cacheControlMaxAge?: number;
+}
+
+/** A listed blob plus the Vercel-specific metadata (uploadedAt) used by TTL cleanup. */
+export interface VercelBlobEntry {
+  pathname: string;
+  url: string;
+  uploadedAt: Date;
+}
+
+/**
+ * Vercel-specific extension over the neutral BlobStoragePort.list(): also surfaces uploadedAt
+ * so the TTL cron can prune by age. Not part of the port contract (other backends carry no
+ * equivalent metadata); consumers needing it depend on this adapter shape explicitly.
+ */
+export interface VercelBlobStorage extends BlobStoragePort {
+  listDetailed(prefix?: string): Promise<{ blobs: VercelBlobEntry[] }>;
+}
+
+/** Parse the public store id from a `vercel_blob_rw_{storeId}_{secret}` token. */
+export function parseVercelStoreId(token: string | undefined): string {
+  if (!token) throw new Error("BLOB_READ_WRITE_TOKEN missing");
+  const m = token.match(/^vercel_blob_rw_([a-zA-Z0-9]+)_/);
+  if (!m) throw new Error("invalid BLOB_READ_WRITE_TOKEN format");
+  return m[1]!.toLowerCase();
+}
+
+export function createVercelBlobStorage(
+  options: VercelBlobAdapterOptions,
+): VercelBlobStorage {
+  const resolveToken = (): string | undefined => options.token ?? options.env.BLOB_READ_WRITE_TOKEN;
+  const cacheControlMaxAge = options.cacheControlMaxAge ?? DEFAULT_CACHE_MAX_AGE_SECONDS;
+  const defaultContentType = options.defaultContentType ?? "image/png";
+
+  return {
+    urlFor(key: string): string {
+      const storeId = parseVercelStoreId(resolveToken());
+      return `https://${storeId}.public.blob.vercel-storage.com/${key}`;
+    },
+
+    async upload(key, data, opts) {
+      const result = await options.sdk.put(key, toUploadBody(data), {
+        access: "public",
+        contentType: opts?.contentType ?? defaultContentType,
+        addRandomSuffix: false,
+        cacheControlMaxAge,
+      });
+      return { url: result.url, pathname: result.pathname };
+    },
+
+    async exists(key) {
+      try {
+        const result = await options.sdk.head(this.urlFor(key));
+        return Boolean(result?.url);
+      } catch {
+        return false;
+      }
+    },
+
+    async delete(keyOrUrl) {
+      // del() accepts a full blob URL or pathname; pass through unchanged.
+      await options.sdk.del(keyOrUrl);
+    },
+
+    async list(prefix) {
+      const result = await options.sdk.list(prefix ? { prefix } : {});
+      return { keys: result.blobs.map((blob) => blob.pathname) };
+    },
+
+    async listDetailed(prefix) {
+      const result = await options.sdk.list(prefix ? { prefix } : {});
+      return {
+        blobs: result.blobs.map((blob) => ({
+          pathname: blob.pathname,
+          url: blob.url,
+          uploadedAt: blob.uploadedAt,
+        })),
+      };
+    },
+  };
+}
+
+// @vercel/blob's put() accepts string | Buffer | Blob | ReadableStream etc. Buffer is a
+// Uint8Array subclass, so both port input shapes pass straight through.
+function toUploadBody(data: Uint8Array | Buffer): Buffer {
+  return Buffer.isBuffer(data) ? data : Buffer.from(data);
+}

package/src/composition/composeBundle.ts

@@ -0,0 +1,109 @@
+// Platform-runtime bundle composition.
+//
+// Resolves the active bundle from the environment and returns its descriptor and port table. Each
+// port slot is filled by one binder, keyed by the bundle's declared capability for that slot. A
+// slot without a binder, or whose binder declines the capability, stays null: callers treat an
+// unbound port as "use the deployment's direct path", never as a silent substitute.
+//
+// The package supplies a default binder for the blob slot. The HTTP, scheduler, data, migrations,
+// analytics and transactional slots carry deployment values (route tables, jobs, the database
+// client factory, migration catalogue, analytics provider, delivery runtime), so the deployment
+// supplies them; `createDataBindings` builds the data binder.
+
+import type {
+  AnalyticsPort,
+  BlobStoragePort,
+  DataGatewayPort,
+  HttpRuntimePort,
+  MigrationRunnerPort,
+  SchedulerPort,
+  TransactionalRuntimePort,
+} from "@openlup/core/platform-runtime";
+
+import { bindBlobPort, type SupabaseStorageClient } from "../blob/index.js";
+import { createServiceClient, readSupabaseDataGatewayEnv } from "../data/index.js";
+import {
+  getBundleDescriptor,
+  resolveBlobCapability,
+  resolveBundleId,
+  type PlatformBundleDescriptor,
+  type PlatformBundleId,
+} from "../kernel/index.js";
+
+type Env = Record<string, string | undefined>;
+
+export interface PlatformBundlePorts {
+  http: HttpRuntimePort | null;
+  scheduler: SchedulerPort | null;
+  blob: BlobStoragePort | null;
+  data: DataGatewayPort | null;
+  migrations: MigrationRunnerPort | null;
+  analytics: AnalyticsPort | null;
+  transactional: TransactionalRuntimePort | null;
+}
+
+export interface PlatformBundle {
+  id: PlatformBundleId;
+  descriptor: PlatformBundleDescriptor;
+  ports: PlatformBundlePorts;
+}
+
+/**
+ * One binder per port slot. Each receives the slot's capability and the environment; the blob
+ * binder receives the selected blob capability (`PLATFORM_BLOB`, else the bundle's own), and the
+ * transactional binder also receives the bundle's data capability.
+ */
+export interface PlatformBundleBinders {
+  /**
+   * The supabase-js `createClient` used by the default Supabase Storage blob binder. Declared
+   * structurally here so the composition entry's declarations reference no data-module type.
+   */
+  createSupabaseClient?: (
+    url: string,
+    key: string,
+    options?: { auth?: { persistSession?: boolean; autoRefreshToken?: boolean } },
+  ) => unknown;
+  http?: (capability: string, env: Env) => HttpRuntimePort | null;
+  scheduler?: (capability: string, env: Env) => SchedulerPort | null;
+  /** Defaults to `bindBlobPort`. */
+  blob?: (capability: string, env: Env) => BlobStoragePort | null;
+  /** For example `createDataBindings(...).bindDataPort`. */
+  data?: (capability: string, env: Env) => DataGatewayPort | null;
+  migrations?: (capability: string, env: Env) => MigrationRunnerPort | null;
+  analytics?: (capability: string, env: Env) => AnalyticsPort | null;
+  transactional?: (capability: string, dataCapability: string, env: Env) => TransactionalRuntimePort | null;
+}
+
+export type ComposeBundle = (env: Env) => PlatformBundle;
+
+/** Build the deployment's composition root from its port binders. */
+export function createBundleComposer(binders: PlatformBundleBinders = {}): ComposeBundle {
+  const bindBlob = binders.blob ?? ((capability: string, env: Env) => {
+    const settings = capability === "supabase" ? readSupabaseDataGatewayEnv({
+      ...env,
+      SUPABASE_URL: env.SUPABASE_URL?.trim() || env.VITE_SUPABASE_URL?.trim(),
+    }) : null;
+    const createSupabaseClient = binders.createSupabaseClient;
+    return bindBlobPort(capability, env, {
+      supabaseStorageClient: settings && createSupabaseClient
+        ? () => createServiceClient(settings, createSupabaseClient) as SupabaseStorageClient
+        : undefined,
+    });
+  });
+  return function composeBundle(env: Env): PlatformBundle {
+    const id = resolveBundleId(env);
+    const descriptor = getBundleDescriptor(id);
+    const { capabilities } = descriptor;
+    const ports: PlatformBundlePorts = {
+      http: binders.http?.(capabilities.http, env) ?? null,
+      scheduler: null,
+      blob: bindBlob(resolveBlobCapability(descriptor, env), env),
+      data: binders.data?.(capabilities.data, env) ?? null,
+      migrations: binders.migrations?.(capabilities.migrations, env) ?? null,
+      analytics: binders.analytics?.(capabilities.analytics, env) ?? null,
+      transactional: binders.transactional?.(capabilities.transactional, capabilities.data, env) ?? null,
+    };
+    ports.scheduler = binders.scheduler?.(capabilities.scheduler, env) ?? null;
+    return { id, descriptor, ports };
+  };
+}

package/src/composition/httpBinding.ts

@@ -0,0 +1,30 @@
+// HTTP slot binding for the Node runtime.
+//
+// Only a bundle whose `http` capability is "node" receives a Node runtime; a hosted bundle keeps
+// `http: null` and serves its route table through its own function entrypoint. The scheduled-route
+// resolver mounts exactly the jobs the deployment declared, so an undeclared `/api/cron/<id>`
+// path stays a 404 and a declared job without an entrypoint fails visibly when called.
+
+import type { HttpRuntimePort } from "@openlup/core/platform-runtime";
+
+import type { EntrypointLoader } from "../http/index.js";
+import { createNodeHttpRuntime, type NodeHttpRuntimeOptions } from "../http/index.js";
+import type { ScheduledJobDeclaration } from "../scheduler/index.js";
+
+/** Mount only the scheduled routes declared by the job registry. */
+export function createScheduledEntrypointResolver(
+  jobs: readonly ScheduledJobDeclaration[],
+  load: (jobId: string) => ReturnType<EntrypointLoader>,
+): (jobId: string) => EntrypointLoader | null {
+  const declared = new Set(jobs.map((job) => job.jobId));
+  return (jobId) => declared.has(jobId) ? () => load(jobId) : null;
+}
+
+/** Build the http port for a bundle capability ("node" => Node runtime; else null). */
+export function bindNodeHttpPort(
+  capability: string,
+  options: () => NodeHttpRuntimeOptions,
+): HttpRuntimePort | null {
+  if (capability !== "node") return null;
+  return createNodeHttpRuntime(options());
+}

package/src/composition/index.ts

@@ -0,0 +1,17 @@
+export {
+  createBundleComposer,
+  type ComposeBundle,
+  type PlatformBundle,
+  type PlatformBundleBinders,
+  type PlatformBundlePorts,
+} from "./composeBundle.js";
+export { bindNodeHttpPort, createScheduledEntrypointResolver } from "./httpBinding.js";
+export {
+  createNodeHost,
+  type NodeHost,
+  type NodeHostAdmission,
+  type NodeHostDependencies,
+  type NodeSchedulerProfile,
+  type ServeNodeOptions,
+  type ServeNodeResult,
+} from "./nodeHost.js";