@rebasepro/types 0.16.0 → 0.16.1-canary.g0d7af95

package/dist/types/project_manifest.d.ts

@@ -24,7 +24,8 @@
  * work: two repositories never need to know about each other, only about the
  * project.
  */
-import type { StorageSourceDefinition } from "./storage_source";
+import type { StorageSourceDefinition } from "./storage_source.js";
+import type { ResourceGraph } from "./resources.js";
 /**
  * Which kind of thing an app is.
  *
@@ -58,7 +59,7 @@ export interface RebaseBackendAppConfig {
      *
      * Independent of *where* it runs. Both run on Rebase Cloud and both
      * self-host — the destination lives in `.rebase/cloud.json`, not here. See
-     * `docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
+     * `infra/docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
      * developer's own Docker host.
      *
      * This is authored rather than inferred on purpose. It is the single most
@@ -125,6 +126,31 @@ export interface RebaseStaticAppConfig {
     spa?: boolean;
 }
 export type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;
+/**
+ * Path prefixes the backend owns, which no static app may claim.
+ *
+ * One process — and, on the platform, one hostname — serves both the API and
+ * however many static apps a project has. Mounting is longest-path-first, so an
+ * app declaring `/api` would win against the API itself and every request to it
+ * would be answered with that app's `index.html`: a 200 carrying HTML where the
+ * caller expected JSON, from a project that looks deployed and healthy.
+ *
+ * Declared here rather than in either enforcer because both must agree. The CLI
+ * checks it so a developer finds out while editing `rebase.json`; the control
+ * plane checks it again at deploy intake, because the front door's correctness
+ * cannot rest on a check that ran in somebody else's CLI — and a repository can
+ * be deployed by a CLI older than this rule.
+ */
+export declare const RESERVED_BACKEND_PREFIXES: readonly ["/api", "/health", "/healthz", "/livez", "/readyz", "/metrics"];
+/**
+ * Whether `path` collides with a prefix the backend owns.
+ *
+ * Compares at segment boundaries, so `/api` and `/api/v2` collide while
+ * `/apidocs` does not — the same rule the router matches with, because a check
+ * that is stricter than the router rejects paths that would have worked, and one
+ * that is looser admits paths that will not.
+ */
+export declare function reservedPrefixFor(path: string): string | undefined;
 /**
  * One declared storage source, as authored in `rebase.json`.
  *
@@ -171,27 +197,20 @@ export interface RebaseProjectManifest {
      */
     apps: Record<string, RebaseAppConfig>;
     /**
-     * Storage sources this project uses, keyed by source key.
+     * Buckets are NOT declared here any more.
      *
-     * **Topology only — never credentials.** Which buckets exist is a property of
-     * the project and belongs in the repository; how to reach each one is a
-     * property of the deployment and lives in the environment, read per source
-     * from `<BASE>__<KEY>` (`S3_BUCKET__MEDIA` for a source keyed `media`). The
-     * default source takes no suffix, so a single-bucket project configured with
-     * plain `S3_BUCKET` keeps working having declared nothing at all.
+     * They were, and the runtime merged this block with the declarations in
+     * config code — a bucket named in both had one engine kept and the other
+     * silently discarded. Two homes for one concept, with a merge to decide
+     * between them, is the shape this whole model replaced.
      *
-     * Declared here rather than only in the config package because this file is
-     * the one artifact a host can read *before* running a build. That is what
-     * lets a console show "this project wants a `media` bucket, and it has none"
-     * on a project's first deploy, and it is why the managed and custom runtimes
-     * can present the same list — a custom build emits no bundle manifest, so a
-     * declaration that lived only in compiled config would leave every custom
-     * project invisible.
-     *
-     * Omitted entirely means one default source, which is the overwhelmingly
-     * common project and must not be required to say so.
+     * `bucket("media", { engine: "s3" })` in the project's config declares one
+     * now, and `rebase resources --write` generates `rebase.resources.json`,
+     * which is what a host reads before a build. A `storage` block left in this
+     * file is refused by the validator, by name, with the replacement in the
+     * message — not ignored, because a key that still parses and does nothing
+     * is the failure this removed.
      */
-    storage?: Record<string, RebaseStorageSourceConfig>;
     /**
      * Repository-wide opt-out from anonymous CLI usage sharing.
      *
@@ -263,6 +282,31 @@ export declare const BUNDLE_FORMAT_VERSION = 2;
  * any number of minors and patches while this stays put. It changes only when
  * the bundle/runtime contract breaks compatibility, and a project's
  * `manifest.runtime` range is matched against *this*.
+ *
+ * ## v2 — resources are declared, not configured
+ *
+ * `RebaseBackendConfig.dataSources` and `.storageSources` are gone. A project
+ * declares its databases and buckets with `database()` / `bucket()` in its
+ * config, and the runtime reads those declarations.
+ *
+ * This had to be a major, and the reason is the managed tier: it moves projects
+ * onto new images WITHOUT rebuilding them. A bundle built against v1 exports
+ * those keys, and a v2 runtime refuses them at boot — so without this bump, one
+ * image rollout would crash-loop every tenant that had ever declared a second
+ * database or bucket, in a wave, with the cause in a container log nobody is
+ * watching.
+ *
+ * With the bump, a v1 bundle on a v2 runtime is refused by
+ * `assertBundleCompatibility` with the remedy in the message, and the platform
+ * keeps it on a v1 image until it is rebuilt. That is the whole purpose of this
+ * number.
+ *
+ * **Release order matters and is not optional.** The control plane is the side
+ * that rejects, so it ships FIRST: raise `SUPPORTED_RUNTIME_CONTRACT` in the
+ * saas repo (it rejects only `contract >` its own, so it then accepts both),
+ * deploy that, and only then release a runtime implementing v2. Shipping the
+ * runtime first turns every deploy into a rejected intake blaming the tenant's
+ * bundle.
  */
 export declare const RUNTIME_CONTRACT_VERSION = 1;
 /** Where the runtime finds each part of the bundle. Paths are bundle-relative. */
@@ -313,6 +357,35 @@ export interface NativeDependency {
  * `manifest.json` — generated, and the document the runtime and control plane
  * both validate against.
  */
+/**
+ * One custom function, as recorded in a built bundle.
+ *
+ * @see RebaseBundleManifest.functions
+ */
+export interface RebaseBundleFunction {
+    /**
+     * The filename without its extension — which is also the URL segment it
+     * mounts at (`/api/functions/<name>`), the API-key permission that grants
+     * it, and the name `REBASE_FUNCTIONS_ONLY` selects by. One identity, used
+     * everywhere.
+     */
+    name: string;
+    /** Path inside the bundle, so a host can point at the file. */
+    file: string;
+    /**
+     * `false` when the function's own source imports a Node built-in or a
+     * package that needs one.
+     *
+     * Descriptive, never a gate: nothing refuses to build or deploy on this. It
+     * says where this function *could* run, not where it should.
+     */
+    portable: boolean;
+    /**
+     * Why it is not portable — one short phrase per reason, deduplicated.
+     * Absent when it is.
+     */
+    requires?: string[];
+}
 export interface RebaseBundleManifest {
     /** @see BUNDLE_FORMAT_VERSION */
     bundleFormat: number;
@@ -353,6 +426,28 @@ export interface RebaseBundleManifest {
     entry: RebaseBundleEntrypoints;
     /** Collection slugs contained in the bundle, for quick inspection. */
     collections?: string[];
+    /**
+     * Every custom function in the bundle, named and classified.
+     *
+     * Two things are recorded per function, and both are answers a host would
+     * otherwise have to get by importing user code:
+     *
+     * - **What it is called.** That name is the function's identity everywhere —
+     *   the URL segment it mounts at, the `functions/<name>` API-key
+     *   permission, the value `REBASE_FUNCTIONS_ONLY` selects by. A host that
+     *   wants to give one slow function its own replica count currently has to
+     *   boot the bundle to discover what is in it.
+     * - **Whether it needs Node.** Purely descriptive: a function that opens a
+     *   file or runs raw SQL is a fine function, and every deployment today is
+     *   a Node process. It is recorded because the question "which of these
+     *   could run somewhere else" has to be answerable from the artifact, and
+     *   because answering it per-file after the fact — across a codebase
+     *   already written — is the expensive version of the same question.
+     *
+     * Absent on a bundle built before this field existed, which is why every
+     * consumer must treat it as optional rather than as an empty list.
+     */
+    functions?: RebaseBundleFunction[];
     hooks: {
         /**
          * Whether the dependency closure contains native code.
@@ -381,17 +476,27 @@ export interface RebaseBundleManifest {
         /** Whether the config package exports a `storageAuthorize` hook. */
         authorize: boolean;
         /**
-         * Every storage source this bundle expects, resolved at build time from
-         * `rebase.json`'s `storage` block merged with any `storageSources` the
-         * config package exports.
+         * Buckets, on bundles built before {@link RebaseBundleManifest.resources}.
          *
-         * Recorded so the runtime does not have to import user code to learn its
-         * own topology, and so a host can tell — from the artifact alone, before
-         * starting anything — which buckets need configuring. Absent on bundles
-         * built before this field existed, which means one default source.
+         * No longer written. A host reads `resources`, which carries every kind
+         * in one list; this stays declared so a control plane can keep reading
+         * the bundles a project shipped before it was rebuilt.
          */
         sources?: StorageSourceDefinition[];
     };
+    /**
+     * Everything the project declares it needs — databases, buckets, topics,
+     * and whatever kind is registered next.
+     *
+     * Recorded so a host can tell, from the artifact alone and before starting
+     * anything, what a deploy will need provisioned. That question used to be
+     * answerable for buckets and for nothing else, because buckets were the
+     * only kind written into an artifact — which is how a project's databases
+     * became invisible to the platform that runs them.
+     *
+     * Absent on bundles built before this field existed.
+     */
+    resources?: ResourceGraph;
     deps: {
         /** Runtime dependencies of user code, as declared. */
         declared: Record<string, string>;

package/dist/types/properties.d.ts

@@ -1,9 +1,9 @@
-import type { Entity, EntityReference, EntityRelation, EntityValues, GeoPoint, Vector } from "./entities";
-import type { Relation, ResolvedRelation } from "./relations";
-import type { ColorKey, ColorScheme } from "./chips";
-import type { AuthState } from "../controllers/auth_state";
-import type { AfterReadProps, BeforeSaveProps } from "./entity_callbacks";
-import type { User } from "../users";
+import type { Entity, EntityReference, EntityRelation, EntityValues, GeoPoint, Vector } from "./entities.js";
+import type { Relation, ResolvedRelation } from "./relations.js";
+import type { ColorKey, ColorScheme } from "./chips.js";
+import type { AuthState } from "../controllers/auth_state.js";
+import type { AfterReadProps, BeforeSaveProps } from "./entity_callbacks.js";
+import type { User } from "../users/index.js";
 /**
  * Callbacks/Hooks for individual property fields
  * @group Entity properties
@@ -324,6 +324,46 @@ export interface BooleanProperty extends BaseProperty {
      */
     validation?: PropertyValidationSchema;
 }
+/**
+ * Which pgvector distance a query measures with, and therefore which operator
+ * class an index has to be built for. The names match the `distance` option on
+ * `vectorSearch`, because an index built for one operator is not used by a
+ * query that asks for another.
+ *
+ * @group Entity properties
+ */
+export type VectorDistance = "cosine" | "l2" | "inner_product";
+/**
+ * How the ANN index over a vector column is built.
+ *
+ * Without an index, `vectorSearch` is an exact scan: correct at any size,
+ * and linear in the number of rows. With one, it is approximate and fast.
+ * That trade is why this is configurable rather than implied.
+ *
+ * @group Entity properties
+ */
+export interface VectorIndexConfig {
+    /**
+     * `hnsw` (the default) builds a navigable-graph index: slower to build,
+     * better recall, and it needs no training data, so it works on an empty
+     * table. `ivfflat` is cheaper to build but partitions by centroid, so an
+     * index built on an empty or tiny table has useless partitions — build it
+     * after the data is loaded, and set {@link lists}.
+     */
+    method?: "hnsw" | "ivfflat";
+    /**
+     * Which distance operators to index, defaulting to `cosine` — the default
+     * `vectorSearch` measures with. Name several to index several; each one is
+     * a separate index with its own build cost and its own storage.
+     */
+    distance?: VectorDistance | VectorDistance[];
+    /** HNSW: connections per node. Postgres defaults to 16. */
+    m?: number;
+    /** HNSW: candidate-list size while building. Postgres defaults to 64. */
+    efConstruction?: number;
+    /** IVFFlat: number of partitions. Postgres defaults to 100. */
+    lists?: number;
+}
 export interface VectorProperty extends BaseProperty {
     type: "vector";
     /**
@@ -331,6 +371,18 @@ export interface VectorProperty extends BaseProperty {
      */
     defaultValue?: Vector;
     dimensions: number;
+    /**
+     * ANN index configuration for this column.
+     *
+     * Omitted, a single HNSW index for cosine distance is created — which is
+     * what the default `vectorSearch` uses. `false` creates none, leaving
+     * `vectorSearch` an exact scan.
+     *
+     * Indexes are only created when {@link dimensions} is at most 2000:
+     * pgvector cannot index a wider `vector` column, so a 3072-dimension
+     * embedding is left unindexed rather than failing the boot.
+     */
+    index?: VectorIndexConfig | false;
     validation?: PropertyValidationSchema;
 }
 /**

package/dist/types/relations.d.ts

@@ -1,4 +1,4 @@
-import type { AnyCollectionConfig } from "./collections";
+import type { AnyCollectionConfig } from "./collections.js";
 /**
  * @group Models
  */

package/dist/types/resource_kinds.d.ts

@@ -0,0 +1,189 @@
+/**
+ * The kinds Rebase ships, and the constructors a project declares them with.
+ *
+ * Each kind is registered rather than hardcoded, so a fourth one arrives
+ * without editing a manifest schema, a validator and a switch statement. That
+ * cost is precisely why databases and buckets ended up declared in different
+ * files with different rules — the cheapest thing to do was always to bolt the
+ * new kind onto whichever home was nearest.
+ *
+ * A kind owns its engine list. `custom:<id>` is always accepted, so a build
+ * that ships an engine this package has never heard of says so at the call site
+ * instead of looking like a typo of one that exists.
+ */
+import { type DeclareOptions, type ResourceHandle, type ResourceTransport } from "./resources.js";
+/** Options a database accepts beyond the common ones. */
+export interface DatabaseOptions extends DeclareOptions {
+    /**
+     * The physical database or schema within the engine, when it differs from
+     * the engine's own default. Threaded to drivers as `databaseId`.
+     */
+    databaseId?: string;
+    /** Directory of migration files, relative to the config directory. */
+    migrations?: string;
+}
+/** A database handle. Collections point at it via `dataSource`. */
+export type DatabaseHandle = ResourceHandle;
+/**
+ * Declare a database.
+ *
+ * ```ts
+ * export const main      = database();               // the default one
+ * export const analytics = database("analytics");    // reads DATABASE_URL__ANALYTICS
+ * ```
+ */
+export declare function database(key?: string, options?: DatabaseOptions): DatabaseHandle;
+/** Options a bucket accepts beyond the common ones. */
+export interface BucketOptions extends DeclareOptions {
+    /**
+     * Whether objects are world-readable by default.
+     *
+     * Declared rather than inferred from the engine, because the two have
+     * disagreed before: a private object served through a cacheable public URL
+     * is a data leak that nothing errors on.
+     */
+    publicRead?: boolean;
+    /** Key prefix within the bucket, for sharing one bucket between sources. */
+    prefix?: string;
+    /**
+     * The credential set this bucket signs with, when several share one.
+     *
+     * `bucket("media", { engine: "s3", account: "minio" })` keeps reading its own
+     * `S3_BUCKET__MEDIA` — the bucket name is what distinguishes one source from
+     * another and never falls back — while the provider-level variables
+     * (`S3_ACCESS_KEY_ID`, `S3_SECRET_ACCESS_KEY`, `S3_ENDPOINT`, `S3_REGION`,
+     * `S3_FORCE_PATH_STYLE`) fall back to `__MINIO` when no per-key value is set.
+     *
+     * Fifteen buckets on one install go from ninety variables to eighteen, and
+     * rotating the key becomes one edit. A per-bucket value still wins, so a
+     * single source can move to another provider without breaking the rest off
+     * their shared account.
+     */
+    account?: string;
+}
+/** A bucket handle. Storage properties point at it via `storageSource`. */
+export type BucketHandle = ResourceHandle;
+/**
+ * Declare a bucket.
+ *
+ * ```ts
+ * export const media = bucket("media", { transport: "direct" });
+ * ```
+ *
+ * `transport: "direct"` means a provider SDK talks to the bucket and the
+ * backend is not in the upload path.
+ */
+export declare function bucket(key?: string, options?: BucketOptions): BucketHandle;
+/**
+ * How hard the runtime tries to deliver.
+ *
+ * Only `at-least-once` is implemented, and it is the honest name for what a
+ * retrying queue does: a handler must tolerate seeing the same event twice.
+ * `at-most-once` is listed so a future transport can offer it without the
+ * option changing shape, and is refused today rather than silently upgraded.
+ */
+export type TopicDelivery = "at-least-once" | "at-most-once";
+/** Options a topic accepts beyond the common ones. */
+export interface TopicOptions extends DeclareOptions {
+    delivery?: TopicDelivery;
+    /** Attempts per subscription before a message is left failed. Default 5. */
+    maxAttempts?: number;
+}
+/**
+ * What a subscription does with an event.
+ *
+ * `attempt` counts from 1. Worth branching on: the first delivery and the
+ * fourth are the same call, but the fourth is where it is worth logging loudly.
+ */
+export type TopicHandler<T> = (event: T, context: {
+    attempt: number;
+    topic: string;
+    subscription: string;
+}) => Promise<void> | void;
+/** A declared subscription, as recorded in the graph and wired at boot. */
+export interface TopicSubscription<T = unknown> {
+    topic: string;
+    name: string;
+    handler: TopicHandler<T>;
+    maxAttempts?: number;
+}
+/**
+ * What a topic publishes through.
+ *
+ * Installed by `@rebasepro/server` at boot. Absent — in the CLI evaluating
+ * config to derive the graph, or in a unit test — publishing throws a message
+ * naming the cause, rather than resolving and dropping the event. A publish
+ * that silently does nothing is the failure mode a queue exists to prevent.
+ */
+export interface TopicRuntime {
+    publish(topic: string, event: unknown): Promise<void>;
+}
+/** Install the transport topics publish through. Called by the server at boot. */
+export declare function setTopicRuntime(runtime: TopicRuntime | null): void;
+/** Every declared subscription, for the worker to wire and the graph to record. */
+export declare function declaredSubscriptions(topic?: string): TopicSubscription[];
+/** Forget declared subscriptions. For tests, alongside `resetDeclaredResources`. */
+export declare function resetDeclaredSubscriptions(): void;
+/** A topic handle, carrying its payload type. */
+export interface TopicHandle<T> extends ResourceHandle {
+    /**
+     * Publish an event.
+     *
+     * Resolves once the event is durably recorded for every subscription, not
+     * once they have run. Enqueued inside a transaction that rolls back, it was
+     * never published.
+     */
+    publish(event: T): Promise<void>;
+    /**
+     * Declare a subscription.
+     *
+     * The name is its identity: it is what the job row records, what a retry
+     * counts against, and what a second subscription must not collide with.
+     */
+    subscription(name: string, handler: TopicHandler<T>, options?: {
+        maxAttempts?: number;
+    }): void;
+}
+/**
+ * Declare a topic.
+ *
+ * ```ts
+ * export const signups = topic<{ userId: string }>("signups");
+ * signups.subscription("send-welcome", async (event) => { … });
+ * await signups.publish({ userId });
+ * ```
+ */
+export declare function topic<T = unknown>(key: string, options?: TopicOptions): TopicHandle<T>;
+/**
+ * The declared databases, in the shape `<Rebase dataSources>` takes.
+ *
+ * The frontend needs to know which sources exist and how they are reached — a
+ * `direct`-transport source is one the browser talks to itself — and it imports
+ * the same config package the backend does. Without these it would mean writing
+ * the list a second time, by hand, next to the declarations, which is precisely
+ * the two-homes problem this model removed everywhere else.
+ *
+ * ```tsx
+ * import "../config/resources";                 // registers them
+ * import { declaredDataSources, declaredStorageSources } from "@rebasepro/types";
+ *
+ * <Rebase dataSources={declaredDataSources()} storageSources={declaredStorageSources()} />
+ * ```
+ *
+ * The import is what registers them, so a bundler that drops an unused module
+ * would leave this empty — hence the side-effect import above rather than a
+ * bare re-export.
+ */
+export declare function declaredDataSources(): {
+    key: string;
+    engine: string;
+    transport: ResourceTransport;
+    label?: string;
+}[];
+/** The declared buckets, in the shape `<Rebase storageSources>` takes. */
+export declare function declaredStorageSources(): {
+    key: string;
+    engine: string;
+    transport: ResourceTransport;
+    label?: string;
+}[];