@rebasepro/types 0.16.0 → 0.16.1-canary.g041c925
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/call_context.d.ts +5 -5
- package/dist/controllers/auth_state.d.ts +1 -1
- package/dist/controllers/client.d.ts +22 -9
- package/dist/controllers/collection_registry.d.ts +2 -2
- package/dist/controllers/data.d.ts +4 -12
- package/dist/controllers/data_driver.d.ts +7 -7
- package/dist/controllers/email.d.ts +54 -2
- package/dist/controllers/index.d.ts +8 -9
- package/dist/controllers/storage.d.ts +4 -4
- package/dist/index.d.ts +5 -5
- package/dist/index.es.js +429 -3
- package/dist/index.es.js.map +1 -1
- package/dist/types/admin_block.d.ts +1 -1
- package/dist/types/auth_adapter.d.ts +18 -9
- package/dist/types/backend.d.ts +23 -10
- package/dist/types/collection_contract.d.ts +1 -1
- package/dist/types/collections.d.ts +16 -9
- package/dist/types/component_ref.d.ts +3 -2
- package/dist/types/cron.d.ts +1 -25
- package/dist/types/data_source.d.ts +1 -1
- package/dist/types/database_adapter.d.ts +5 -5
- package/dist/types/entities.d.ts +1 -1
- package/dist/types/entity_callbacks.d.ts +4 -4
- package/dist/types/index.d.ts +32 -29
- package/dist/types/project_manifest.d.ts +132 -27
- package/dist/types/properties.d.ts +58 -6
- package/dist/types/relations.d.ts +1 -1
- package/dist/types/resource_kinds.d.ts +174 -0
- package/dist/types/resources.d.ts +197 -0
- package/dist/types/schema_editing.d.ts +127 -0
- package/dist/types/schema_version.d.ts +1 -1
- package/dist/types/security_rules.d.ts +1 -1
- package/dist/users/index.d.ts +1 -1
- package/package.json +2 -2
- package/src/controllers/client.ts +14 -1
- package/src/controllers/data.ts +0 -9
- package/src/controllers/email.ts +55 -2
- package/src/controllers/index.ts +0 -1
- package/src/controllers/storage.ts +4 -4
- package/src/types/admin_block.ts +1 -2
- package/src/types/auth_adapter.ts +18 -10
- package/src/types/backend.ts +18 -1
- package/src/types/collections.ts +9 -2
- package/src/types/component_ref.ts +3 -2
- package/src/types/cron.ts +0 -24
- package/src/types/index.ts +3 -0
- package/src/types/project_manifest.ts +139 -26
- package/src/types/properties.ts +54 -0
- package/src/types/resource_kinds.ts +309 -0
- package/src/types/resources.ts +368 -0
- package/src/types/schema_editing.ts +154 -0
- package/dist/controllers/database_admin.d.ts +0 -11
- package/src/controllers/database_admin.ts +0 -22
package/src/controllers/email.ts
CHANGED
|
@@ -20,6 +20,51 @@ export interface EmailSendOptions {
|
|
|
20
20
|
text?: string;
|
|
21
21
|
/** Optional reply-to address. */
|
|
22
22
|
replyTo?: string;
|
|
23
|
+
/**
|
|
24
|
+
* Additional headers, verbatim.
|
|
25
|
+
*
|
|
26
|
+
* The reason this exists is that several things a real sender must do are
|
|
27
|
+
* only expressible as headers, and without a passthrough an application had
|
|
28
|
+
* to choose between not doing them and not using this interface:
|
|
29
|
+
*
|
|
30
|
+
* - `List-Unsubscribe` and `List-Unsubscribe-Post`, which give a mail client
|
|
31
|
+
* its own one-click opt-out. The large providers weigh their presence when
|
|
32
|
+
* deciding whether bulk mail reaches an inbox at all.
|
|
33
|
+
* - `In-Reply-To` and `References`, without which a reply is a new thread.
|
|
34
|
+
*
|
|
35
|
+
* **Values are validated, not escaped.** A value containing CR or LF is
|
|
36
|
+
* rejected rather than sanitised, because a newline in a header value ends
|
|
37
|
+
* the header and starts a new one — so a field built from user input is an
|
|
38
|
+
* injection point for `Bcc:` and anything else. Rejecting is the only safe
|
|
39
|
+
* response: silently stripping the newline would deliver a message the
|
|
40
|
+
* caller did not write, and neither would tell them.
|
|
41
|
+
*/
|
|
42
|
+
headers?: Record<string, string>;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* What the provider reported about a message it accepted.
|
|
47
|
+
*
|
|
48
|
+
* Every field is optional because not every backend reports them: a custom
|
|
49
|
+
* `sendEmail` function that posts to an HTTP API may know nothing beyond "no
|
|
50
|
+
* error". An absent `messageId` therefore means "not reported", never "not
|
|
51
|
+
* sent" — the absence of an id is not a delivery failure, which is signalled by
|
|
52
|
+
* a thrown error.
|
|
53
|
+
*/
|
|
54
|
+
export interface EmailSendResult {
|
|
55
|
+
/**
|
|
56
|
+
* The message's RFC 5322 Message-ID, **without** angle brackets.
|
|
57
|
+
*
|
|
58
|
+
* Stripped because this is an identifier to store and compare — against a
|
|
59
|
+
* reply's `In-Reply-To`, most often — and a value that sometimes carries
|
|
60
|
+
* brackets and sometimes does not is a bug waiting in every comparison.
|
|
61
|
+
* Re-add them when writing it into a header: `<${messageId}>`.
|
|
62
|
+
*/
|
|
63
|
+
messageId?: string;
|
|
64
|
+
/** Recipients the provider accepted, when it says. */
|
|
65
|
+
accepted?: string[];
|
|
66
|
+
/** Recipients the provider refused, when it says. A non-empty list is not an error. */
|
|
67
|
+
rejected?: string[];
|
|
23
68
|
}
|
|
24
69
|
|
|
25
70
|
/**
|
|
@@ -29,8 +74,16 @@ export interface EmailSendOptions {
|
|
|
29
74
|
* provider — consumers only interact through this interface.
|
|
30
75
|
*/
|
|
31
76
|
export interface EmailService {
|
|
32
|
-
/**
|
|
33
|
-
|
|
77
|
+
/**
|
|
78
|
+
* Send a single email.
|
|
79
|
+
*
|
|
80
|
+
* Resolves with what the provider reported (see {@link EmailSendResult});
|
|
81
|
+
* throws on failure. It returned `void` before 0.17: an application that
|
|
82
|
+
* sent a message had no way to learn the id the server assigned it, so
|
|
83
|
+
* threading a reply back to the message that prompted it was impossible
|
|
84
|
+
* through this interface. Callers that do not care may still ignore it.
|
|
85
|
+
*/
|
|
86
|
+
send(options: EmailSendOptions): Promise<EmailSendResult>;
|
|
34
87
|
/** Returns `true` when the service has valid credentials / is ready to send. */
|
|
35
88
|
isConfigured(): boolean;
|
|
36
89
|
/** Verify connection/credentials with the email provider. */
|
package/src/controllers/index.ts
CHANGED
|
@@ -68,11 +68,11 @@ export interface UploadFileResult {
|
|
|
68
68
|
/**
|
|
69
69
|
* Fully qualified storage URL for the uploaded file.
|
|
70
70
|
*
|
|
71
|
-
* For example: `s3://my-bucket/path/to/file.png`.
|
|
72
|
-
*
|
|
73
|
-
*
|
|
71
|
+
* For example: `s3://my-bucket/path/to/file.png`. Every controller in the
|
|
72
|
+
* framework returns one — S3, GCS and local alike — and a caller that stores
|
|
73
|
+
* the reference needs it, so it is part of the result rather than a maybe.
|
|
74
74
|
*/
|
|
75
|
-
storageUrl
|
|
75
|
+
storageUrl: string;
|
|
76
76
|
}
|
|
77
77
|
|
|
78
78
|
/**
|
package/src/types/admin_block.ts
CHANGED
|
@@ -83,8 +83,16 @@ export interface AuthAdapterCapabilities {
|
|
|
83
83
|
|
|
84
84
|
/** Supports email/password login. */
|
|
85
85
|
emailPasswordLogin: boolean;
|
|
86
|
-
/**
|
|
87
|
-
|
|
86
|
+
/**
|
|
87
|
+
* Whether self-registration is open **right now**.
|
|
88
|
+
*
|
|
89
|
+
* A runtime answer, not a static feature list: the built-in adapter also
|
|
90
|
+
* reports `true` during the first-user bootstrap window (an empty user
|
|
91
|
+
* table) and `false` the moment `disableSelfRegistration` is set. Whatever
|
|
92
|
+
* this says, `POST /auth/register` does — both read the same predicate, so
|
|
93
|
+
* the UI can never be sent to a form that can only 403.
|
|
94
|
+
*/
|
|
95
|
+
registrationEnabled: boolean;
|
|
88
96
|
/**
|
|
89
97
|
* Supports the end-user password reset flow (emailing a reset link).
|
|
90
98
|
*
|
|
@@ -113,12 +121,15 @@ export interface AuthAdapterCapabilities {
|
|
|
113
121
|
/** Supports passwordless magic link login. */
|
|
114
122
|
magicLink: boolean;
|
|
115
123
|
/**
|
|
116
|
-
*
|
|
124
|
+
* Supports passwordless sign-in with a six-digit code sent by email.
|
|
117
125
|
*
|
|
118
|
-
* Optional so an external adapter
|
|
119
|
-
* absent
|
|
126
|
+
* Optional so that an external adapter written before this existed still
|
|
127
|
+
* satisfies the interface; absent reads as "no", which is what an adapter
|
|
128
|
+
* that has never heard of the flow means.
|
|
120
129
|
*/
|
|
121
|
-
|
|
130
|
+
emailOtp?: boolean;
|
|
131
|
+
/** Whether `POST /auth/anonymous` will mint a credential-less session. */
|
|
132
|
+
anonymousLogin: boolean;
|
|
122
133
|
/** List of enabled OAuth provider IDs (e.g. `["google", "github"]`). */
|
|
123
134
|
enabledProviders: string[];
|
|
124
135
|
|
|
@@ -134,9 +145,6 @@ export interface AuthAdapterCapabilities {
|
|
|
134
145
|
* Only applicable for built-in auth.
|
|
135
146
|
*/
|
|
136
147
|
needsSetup?: boolean;
|
|
137
|
-
|
|
138
|
-
/** Whether new user registration is enabled (may differ from `registration` capability at runtime). */
|
|
139
|
-
registrationEnabled?: boolean;
|
|
140
148
|
}
|
|
141
149
|
|
|
142
150
|
// ─── User Management ────────────────────────────────────────────────────────
|
|
@@ -311,7 +319,7 @@ export interface TransformAuthResponseContext {
|
|
|
311
319
|
/** The authenticated user's ID. */
|
|
312
320
|
uid: string;
|
|
313
321
|
/** The auth method that triggered this response. */
|
|
314
|
-
method: "login" | "register" | "oauth" | "refresh" | "anonymous" | "magic-link" | "mfa";
|
|
322
|
+
method: "login" | "register" | "oauth" | "refresh" | "anonymous" | "magic-link" | "otp" | "mfa";
|
|
315
323
|
/** The raw HTTP request (for reading headers, IP, etc.). */
|
|
316
324
|
request: Request;
|
|
317
325
|
}
|
package/src/types/backend.ts
CHANGED
|
@@ -4,6 +4,7 @@ import type { LogicalCondition } from "../controllers/data";
|
|
|
4
4
|
import type { AuthAdapter } from "./auth_adapter";
|
|
5
5
|
import type { HistoryConfig } from "../controllers/client";
|
|
6
6
|
import type { ChannelBusSetting } from "./channel_bus";
|
|
7
|
+
import type { SchemaEditingAdmin } from "./schema_editing";
|
|
7
8
|
|
|
8
9
|
// =============================================================================
|
|
9
10
|
// DATABASE CONNECTION INTERFACES
|
|
@@ -564,7 +565,23 @@ export interface BranchAdmin {
|
|
|
564
565
|
*
|
|
565
566
|
* @group Admin
|
|
566
567
|
*/
|
|
567
|
-
export type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin>
|
|
568
|
+
export type DatabaseAdmin = Partial<SQLAdmin> & Partial<DocumentAdmin> & Partial<SchemaAdmin>
|
|
569
|
+
& Partial<BranchAdmin> & Partial<SchemaEditingAdmin>;
|
|
570
|
+
|
|
571
|
+
/**
|
|
572
|
+
* Type guard: can this admin plan a live schema change?
|
|
573
|
+
*
|
|
574
|
+
* Planning is engine-specific — it renders DDL, a Drizzle schema and the
|
|
575
|
+
* declarative SQL artifacts — so the implementation lives in the driver
|
|
576
|
+
* package. The server detects the capability structurally, exactly as it does
|
|
577
|
+
* for SQL, rather than importing an engine it is supposed to know nothing
|
|
578
|
+
* about.
|
|
579
|
+
*
|
|
580
|
+
* @group Admin
|
|
581
|
+
*/
|
|
582
|
+
export function isSchemaEditingAdmin(admin: DatabaseAdmin | undefined): admin is SchemaEditingAdmin {
|
|
583
|
+
return !!admin && typeof (admin as SchemaEditingAdmin).planSchemaChange === "function";
|
|
584
|
+
}
|
|
568
585
|
|
|
569
586
|
/**
|
|
570
587
|
* Type guard: does this admin support SQL operations?
|
package/src/types/collections.ts
CHANGED
|
@@ -3,6 +3,7 @@ import type { CollectionCallbacks } from "./entity_callbacks";
|
|
|
3
3
|
import type { EnumValues, Properties, PostgresProperties, FirebaseProperties, MongoProperties } from "./properties";
|
|
4
4
|
|
|
5
5
|
import type { User } from "../users";
|
|
6
|
+
import type { EmailSendResult } from "../controllers/email";
|
|
6
7
|
import type { Relation } from "./relations";
|
|
7
8
|
import type { SecurityRule } from "./security_rules";
|
|
8
9
|
import { getDataSourceCapabilities } from "./data_source";
|
|
@@ -702,8 +703,14 @@ export interface AuthCollectionConfig {
|
|
|
702
703
|
export interface AuthCollectionContext {
|
|
703
704
|
/** Hash a password using the configured algorithm (scrypt by default). */
|
|
704
705
|
hashPassword: (password: string) => Promise<string>;
|
|
705
|
-
/**
|
|
706
|
-
|
|
706
|
+
/**
|
|
707
|
+
* Send an email. Only available when email service is configured.
|
|
708
|
+
*
|
|
709
|
+
* Resolves with what the provider reported — the assigned Message-ID, most
|
|
710
|
+
* usefully — so a hook that sends a message can store the id and later
|
|
711
|
+
* thread a reply back to it. Callers that do not care may ignore it.
|
|
712
|
+
*/
|
|
713
|
+
sendEmail?: (options: { to: string; subject: string; html: string; text?: string }) => Promise<EmailSendResult>;
|
|
707
714
|
/** Whether the email service is configured and available. */
|
|
708
715
|
emailConfigured: boolean;
|
|
709
716
|
/** The app name from email config (for templates). */
|
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
* How a collection points at a UI component without the backend learning about React.
|
|
3
3
|
*
|
|
4
4
|
* This file is the hinge the BaaS/admin split turns on. `ComponentRef` is named
|
|
5
|
-
* by `
|
|
6
|
-
* must stay in the React-free core
|
|
5
|
+
* by a property's `admin` block (`admin.Field`, `admin.Preview`, `admin.Filter`)
|
|
6
|
+
* and imported by `properties.ts`, which must stay in the React-free core
|
|
7
|
+
* because every backend subsystem — validation,
|
|
7
8
|
* the drizzle schema generator, the OpenAPI generator, the SDK codegen — reads
|
|
8
9
|
* property definitions. If `ComponentRef` needed `React.ComponentType`, the whole
|
|
9
10
|
* property model would have to move to the admin layer with it.
|
package/src/types/cron.ts
CHANGED
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import type { RebaseServerClient } from "../controllers/client";
|
|
2
|
-
import type { RebaseSdkData } from "../controllers/data";
|
|
3
2
|
|
|
4
3
|
/**
|
|
5
4
|
* Cron Job type definitions for Rebase.
|
|
@@ -126,29 +125,6 @@ export interface CronJobContext {
|
|
|
126
125
|
*/
|
|
127
126
|
rebase: RebaseServerClient;
|
|
128
127
|
|
|
129
|
-
/**
|
|
130
|
-
* The same object as {@link rebase}, under the name this context used
|
|
131
|
-
* before.
|
|
132
|
-
*
|
|
133
|
-
* @deprecated Use `rebase` instead. Two things made the old name a problem,
|
|
134
|
-
* and neither was cosmetic. It contradicted every other server surface,
|
|
135
|
-
* where the singleton is `rebase` — the previous docstring had to end with
|
|
136
|
-
* *"it is only named `client` here"*. And typing it as `RebaseClient`
|
|
137
|
-
* re-exposed `client.data`, the alias that {@link RebaseServerClient}
|
|
138
|
-
* deliberately `Omit`s so the RLS-bypassing plane has exactly one name and
|
|
139
|
-
* the privilege is visible at the call site. A reader who learned
|
|
140
|
-
* `client.data` here carried it to a collection callback, where
|
|
141
|
-
* `context.data` is the *user-scoped* plane — same spelling, opposite
|
|
142
|
-
* privilege.
|
|
143
|
-
*
|
|
144
|
-
* Still the full server client at runtime, and `data` still resolves, so
|
|
145
|
-
* existing cron files keep working and keep compiling. It will be removed
|
|
146
|
-
* in the next major.
|
|
147
|
-
*/
|
|
148
|
-
client: RebaseServerClient & {
|
|
149
|
-
/** @deprecated Use `rebase.dataAsAdmin` — the name states the privilege. */
|
|
150
|
-
data: RebaseSdkData;
|
|
151
|
-
};
|
|
152
128
|
}
|
|
153
129
|
|
|
154
130
|
// =============================================================================
|
package/src/types/index.ts
CHANGED
|
@@ -14,8 +14,11 @@ export * from "./security_rules";
|
|
|
14
14
|
export * from "./entity_callbacks";
|
|
15
15
|
export * from "./websockets";
|
|
16
16
|
export * from "./backend";
|
|
17
|
+
export * from "./schema_editing";
|
|
17
18
|
export * from "./channel_bus";
|
|
18
19
|
export * from "./data_source";
|
|
20
|
+
export * from "./resources";
|
|
21
|
+
export * from "./resource_kinds";
|
|
19
22
|
export * from "./storage_source";
|
|
20
23
|
export * from "./cron";
|
|
21
24
|
export * from "./backup";
|
|
@@ -26,6 +26,7 @@
|
|
|
26
26
|
*/
|
|
27
27
|
|
|
28
28
|
import type { StorageSourceDefinition } from "./storage_source";
|
|
29
|
+
import type { ResourceGraph } from "./resources";
|
|
29
30
|
|
|
30
31
|
/**
|
|
31
32
|
* Which kind of thing an app is.
|
|
@@ -61,7 +62,7 @@ export interface RebaseBackendAppConfig {
|
|
|
61
62
|
*
|
|
62
63
|
* Independent of *where* it runs. Both run on Rebase Cloud and both
|
|
63
64
|
* self-host — the destination lives in `.rebase/cloud.json`, not here. See
|
|
64
|
-
* `docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
|
|
65
|
+
* `infra/docker/docker-compose.selfhost.yml`, which boots a managed bundle on a
|
|
65
66
|
* developer's own Docker host.
|
|
66
67
|
*
|
|
67
68
|
* This is authored rather than inferred on purpose. It is the single most
|
|
@@ -132,6 +133,38 @@ export interface RebaseStaticAppConfig {
|
|
|
132
133
|
|
|
133
134
|
export type RebaseAppConfig = RebaseBackendAppConfig | RebaseStaticAppConfig;
|
|
134
135
|
|
|
136
|
+
/**
|
|
137
|
+
* Path prefixes the backend owns, which no static app may claim.
|
|
138
|
+
*
|
|
139
|
+
* One process — and, on the platform, one hostname — serves both the API and
|
|
140
|
+
* however many static apps a project has. Mounting is longest-path-first, so an
|
|
141
|
+
* app declaring `/api` would win against the API itself and every request to it
|
|
142
|
+
* would be answered with that app's `index.html`: a 200 carrying HTML where the
|
|
143
|
+
* caller expected JSON, from a project that looks deployed and healthy.
|
|
144
|
+
*
|
|
145
|
+
* Declared here rather than in either enforcer because both must agree. The CLI
|
|
146
|
+
* checks it so a developer finds out while editing `rebase.json`; the control
|
|
147
|
+
* plane checks it again at deploy intake, because the front door's correctness
|
|
148
|
+
* cannot rest on a check that ran in somebody else's CLI — and a repository can
|
|
149
|
+
* be deployed by a CLI older than this rule.
|
|
150
|
+
*/
|
|
151
|
+
export const RESERVED_BACKEND_PREFIXES = ["/api", "/health", "/healthz", "/livez", "/readyz", "/metrics"] as const;
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Whether `path` collides with a prefix the backend owns.
|
|
155
|
+
*
|
|
156
|
+
* Compares at segment boundaries, so `/api` and `/api/v2` collide while
|
|
157
|
+
* `/apidocs` does not — the same rule the router matches with, because a check
|
|
158
|
+
* that is stricter than the router rejects paths that would have worked, and one
|
|
159
|
+
* that is looser admits paths that will not.
|
|
160
|
+
*/
|
|
161
|
+
export function reservedPrefixFor(path: string): string | undefined {
|
|
162
|
+
const normalized = path.endsWith("/") && path !== "/" ? path.slice(0, -1) : path;
|
|
163
|
+
return RESERVED_BACKEND_PREFIXES.find(
|
|
164
|
+
reserved => normalized === reserved || normalized.startsWith(`${reserved}/`)
|
|
165
|
+
);
|
|
166
|
+
}
|
|
167
|
+
|
|
135
168
|
/**
|
|
136
169
|
* One declared storage source, as authored in `rebase.json`.
|
|
137
170
|
*
|
|
@@ -179,27 +212,20 @@ export interface RebaseProjectManifest {
|
|
|
179
212
|
*/
|
|
180
213
|
apps: Record<string, RebaseAppConfig>;
|
|
181
214
|
/**
|
|
182
|
-
*
|
|
215
|
+
* Buckets are NOT declared here any more.
|
|
183
216
|
*
|
|
184
|
-
*
|
|
185
|
-
*
|
|
186
|
-
*
|
|
187
|
-
*
|
|
188
|
-
* default source takes no suffix, so a single-bucket project configured with
|
|
189
|
-
* plain `S3_BUCKET` keeps working having declared nothing at all.
|
|
217
|
+
* They were, and the runtime merged this block with the declarations in
|
|
218
|
+
* config code — a bucket named in both had one engine kept and the other
|
|
219
|
+
* silently discarded. Two homes for one concept, with a merge to decide
|
|
220
|
+
* between them, is the shape this whole model replaced.
|
|
190
221
|
*
|
|
191
|
-
*
|
|
192
|
-
*
|
|
193
|
-
*
|
|
194
|
-
*
|
|
195
|
-
*
|
|
196
|
-
*
|
|
197
|
-
* project invisible.
|
|
198
|
-
*
|
|
199
|
-
* Omitted entirely means one default source, which is the overwhelmingly
|
|
200
|
-
* common project and must not be required to say so.
|
|
222
|
+
* `bucket("media", { engine: "s3" })` in the project's config declares one
|
|
223
|
+
* now, and `rebase resources --write` generates `rebase.resources.json`,
|
|
224
|
+
* which is what a host reads before a build. A `storage` block left in this
|
|
225
|
+
* file is refused by the validator, by name, with the replacement in the
|
|
226
|
+
* message — not ignored, because a key that still parses and does nothing
|
|
227
|
+
* is the failure this removed.
|
|
201
228
|
*/
|
|
202
|
-
storage?: Record<string, RebaseStorageSourceConfig>;
|
|
203
229
|
/**
|
|
204
230
|
* Repository-wide opt-out from anonymous CLI usage sharing.
|
|
205
231
|
*
|
|
@@ -279,6 +305,31 @@ export const BUNDLE_FORMAT_VERSION = 2;
|
|
|
279
305
|
* any number of minors and patches while this stays put. It changes only when
|
|
280
306
|
* the bundle/runtime contract breaks compatibility, and a project's
|
|
281
307
|
* `manifest.runtime` range is matched against *this*.
|
|
308
|
+
*
|
|
309
|
+
* ## v2 — resources are declared, not configured
|
|
310
|
+
*
|
|
311
|
+
* `RebaseBackendConfig.dataSources` and `.storageSources` are gone. A project
|
|
312
|
+
* declares its databases and buckets with `database()` / `bucket()` in its
|
|
313
|
+
* config, and the runtime reads those declarations.
|
|
314
|
+
*
|
|
315
|
+
* This had to be a major, and the reason is the managed tier: it moves projects
|
|
316
|
+
* onto new images WITHOUT rebuilding them. A bundle built against v1 exports
|
|
317
|
+
* those keys, and a v2 runtime refuses them at boot — so without this bump, one
|
|
318
|
+
* image rollout would crash-loop every tenant that had ever declared a second
|
|
319
|
+
* database or bucket, in a wave, with the cause in a container log nobody is
|
|
320
|
+
* watching.
|
|
321
|
+
*
|
|
322
|
+
* With the bump, a v1 bundle on a v2 runtime is refused by
|
|
323
|
+
* `assertBundleCompatibility` with the remedy in the message, and the platform
|
|
324
|
+
* keeps it on a v1 image until it is rebuilt. That is the whole purpose of this
|
|
325
|
+
* number.
|
|
326
|
+
*
|
|
327
|
+
* **Release order matters and is not optional.** The control plane is the side
|
|
328
|
+
* that rejects, so it ships FIRST: raise `SUPPORTED_RUNTIME_CONTRACT` in the
|
|
329
|
+
* saas repo (it rejects only `contract >` its own, so it then accepts both),
|
|
330
|
+
* deploy that, and only then release a runtime implementing v2. Shipping the
|
|
331
|
+
* runtime first turns every deploy into a rejected intake blaming the tenant's
|
|
332
|
+
* bundle.
|
|
282
333
|
*/
|
|
283
334
|
export const RUNTIME_CONTRACT_VERSION = 1;
|
|
284
335
|
|
|
@@ -333,6 +384,36 @@ export interface NativeDependency {
|
|
|
333
384
|
* `manifest.json` — generated, and the document the runtime and control plane
|
|
334
385
|
* both validate against.
|
|
335
386
|
*/
|
|
387
|
+
/**
|
|
388
|
+
* One custom function, as recorded in a built bundle.
|
|
389
|
+
*
|
|
390
|
+
* @see RebaseBundleManifest.functions
|
|
391
|
+
*/
|
|
392
|
+
export interface RebaseBundleFunction {
|
|
393
|
+
/**
|
|
394
|
+
* The filename without its extension — which is also the URL segment it
|
|
395
|
+
* mounts at (`/api/functions/<name>`), the API-key permission that grants
|
|
396
|
+
* it, and the name `REBASE_FUNCTIONS_ONLY` selects by. One identity, used
|
|
397
|
+
* everywhere.
|
|
398
|
+
*/
|
|
399
|
+
name: string;
|
|
400
|
+
/** Path inside the bundle, so a host can point at the file. */
|
|
401
|
+
file: string;
|
|
402
|
+
/**
|
|
403
|
+
* `false` when the function's own source imports a Node built-in or a
|
|
404
|
+
* package that needs one.
|
|
405
|
+
*
|
|
406
|
+
* Descriptive, never a gate: nothing refuses to build or deploy on this. It
|
|
407
|
+
* says where this function *could* run, not where it should.
|
|
408
|
+
*/
|
|
409
|
+
portable: boolean;
|
|
410
|
+
/**
|
|
411
|
+
* Why it is not portable — one short phrase per reason, deduplicated.
|
|
412
|
+
* Absent when it is.
|
|
413
|
+
*/
|
|
414
|
+
requires?: string[];
|
|
415
|
+
}
|
|
416
|
+
|
|
336
417
|
export interface RebaseBundleManifest {
|
|
337
418
|
/** @see BUNDLE_FORMAT_VERSION */
|
|
338
419
|
bundleFormat: number;
|
|
@@ -373,6 +454,28 @@ export interface RebaseBundleManifest {
|
|
|
373
454
|
entry: RebaseBundleEntrypoints;
|
|
374
455
|
/** Collection slugs contained in the bundle, for quick inspection. */
|
|
375
456
|
collections?: string[];
|
|
457
|
+
/**
|
|
458
|
+
* Every custom function in the bundle, named and classified.
|
|
459
|
+
*
|
|
460
|
+
* Two things are recorded per function, and both are answers a host would
|
|
461
|
+
* otherwise have to get by importing user code:
|
|
462
|
+
*
|
|
463
|
+
* - **What it is called.** That name is the function's identity everywhere —
|
|
464
|
+
* the URL segment it mounts at, the `functions/<name>` API-key
|
|
465
|
+
* permission, the value `REBASE_FUNCTIONS_ONLY` selects by. A host that
|
|
466
|
+
* wants to give one slow function its own replica count currently has to
|
|
467
|
+
* boot the bundle to discover what is in it.
|
|
468
|
+
* - **Whether it needs Node.** Purely descriptive: a function that opens a
|
|
469
|
+
* file or runs raw SQL is a fine function, and every deployment today is
|
|
470
|
+
* a Node process. It is recorded because the question "which of these
|
|
471
|
+
* could run somewhere else" has to be answerable from the artifact, and
|
|
472
|
+
* because answering it per-file after the fact — across a codebase
|
|
473
|
+
* already written — is the expensive version of the same question.
|
|
474
|
+
*
|
|
475
|
+
* Absent on a bundle built before this field existed, which is why every
|
|
476
|
+
* consumer must treat it as optional rather than as an empty list.
|
|
477
|
+
*/
|
|
478
|
+
functions?: RebaseBundleFunction[];
|
|
376
479
|
hooks: {
|
|
377
480
|
/**
|
|
378
481
|
* Whether the dependency closure contains native code.
|
|
@@ -401,17 +504,27 @@ export interface RebaseBundleManifest {
|
|
|
401
504
|
/** Whether the config package exports a `storageAuthorize` hook. */
|
|
402
505
|
authorize: boolean;
|
|
403
506
|
/**
|
|
404
|
-
*
|
|
405
|
-
* `rebase.json`'s `storage` block merged with any `storageSources` the
|
|
406
|
-
* config package exports.
|
|
507
|
+
* Buckets, on bundles built before {@link RebaseBundleManifest.resources}.
|
|
407
508
|
*
|
|
408
|
-
*
|
|
409
|
-
*
|
|
410
|
-
*
|
|
411
|
-
* built before this field existed, which means one default source.
|
|
509
|
+
* No longer written. A host reads `resources`, which carries every kind
|
|
510
|
+
* in one list; this stays declared so a control plane can keep reading
|
|
511
|
+
* the bundles a project shipped before it was rebuilt.
|
|
412
512
|
*/
|
|
413
513
|
sources?: StorageSourceDefinition[];
|
|
414
514
|
};
|
|
515
|
+
/**
|
|
516
|
+
* Everything the project declares it needs — databases, buckets, topics,
|
|
517
|
+
* and whatever kind is registered next.
|
|
518
|
+
*
|
|
519
|
+
* Recorded so a host can tell, from the artifact alone and before starting
|
|
520
|
+
* anything, what a deploy will need provisioned. That question used to be
|
|
521
|
+
* answerable for buckets and for nothing else, because buckets were the
|
|
522
|
+
* only kind written into an artifact — which is how a project's databases
|
|
523
|
+
* became invisible to the platform that runs them.
|
|
524
|
+
*
|
|
525
|
+
* Absent on bundles built before this field existed.
|
|
526
|
+
*/
|
|
527
|
+
resources?: ResourceGraph;
|
|
415
528
|
deps: {
|
|
416
529
|
/** Runtime dependencies of user code, as declared. */
|
|
417
530
|
declared: Record<string, string>;
|
package/src/types/properties.ts
CHANGED
|
@@ -400,6 +400,48 @@ export interface BooleanProperty extends BaseProperty {
|
|
|
400
400
|
validation?: PropertyValidationSchema;
|
|
401
401
|
}
|
|
402
402
|
|
|
403
|
+
/**
|
|
404
|
+
* Which pgvector distance a query measures with, and therefore which operator
|
|
405
|
+
* class an index has to be built for. The names match the `distance` option on
|
|
406
|
+
* `vectorSearch`, because an index built for one operator is not used by a
|
|
407
|
+
* query that asks for another.
|
|
408
|
+
*
|
|
409
|
+
* @group Entity properties
|
|
410
|
+
*/
|
|
411
|
+
export type VectorDistance = "cosine" | "l2" | "inner_product";
|
|
412
|
+
|
|
413
|
+
/**
|
|
414
|
+
* How the ANN index over a vector column is built.
|
|
415
|
+
*
|
|
416
|
+
* Without an index, `vectorSearch` is an exact scan: correct at any size,
|
|
417
|
+
* and linear in the number of rows. With one, it is approximate and fast.
|
|
418
|
+
* That trade is why this is configurable rather than implied.
|
|
419
|
+
*
|
|
420
|
+
* @group Entity properties
|
|
421
|
+
*/
|
|
422
|
+
export interface VectorIndexConfig {
|
|
423
|
+
/**
|
|
424
|
+
* `hnsw` (the default) builds a navigable-graph index: slower to build,
|
|
425
|
+
* better recall, and it needs no training data, so it works on an empty
|
|
426
|
+
* table. `ivfflat` is cheaper to build but partitions by centroid, so an
|
|
427
|
+
* index built on an empty or tiny table has useless partitions — build it
|
|
428
|
+
* after the data is loaded, and set {@link lists}.
|
|
429
|
+
*/
|
|
430
|
+
method?: "hnsw" | "ivfflat";
|
|
431
|
+
/**
|
|
432
|
+
* Which distance operators to index, defaulting to `cosine` — the default
|
|
433
|
+
* `vectorSearch` measures with. Name several to index several; each one is
|
|
434
|
+
* a separate index with its own build cost and its own storage.
|
|
435
|
+
*/
|
|
436
|
+
distance?: VectorDistance | VectorDistance[];
|
|
437
|
+
/** HNSW: connections per node. Postgres defaults to 16. */
|
|
438
|
+
m?: number;
|
|
439
|
+
/** HNSW: candidate-list size while building. Postgres defaults to 64. */
|
|
440
|
+
efConstruction?: number;
|
|
441
|
+
/** IVFFlat: number of partitions. Postgres defaults to 100. */
|
|
442
|
+
lists?: number;
|
|
443
|
+
}
|
|
444
|
+
|
|
403
445
|
export interface VectorProperty extends BaseProperty {
|
|
404
446
|
type: "vector";
|
|
405
447
|
/**
|
|
@@ -407,6 +449,18 @@ export interface VectorProperty extends BaseProperty {
|
|
|
407
449
|
*/
|
|
408
450
|
defaultValue?: Vector;
|
|
409
451
|
dimensions: number;
|
|
452
|
+
/**
|
|
453
|
+
* ANN index configuration for this column.
|
|
454
|
+
*
|
|
455
|
+
* Omitted, a single HNSW index for cosine distance is created — which is
|
|
456
|
+
* what the default `vectorSearch` uses. `false` creates none, leaving
|
|
457
|
+
* `vectorSearch` an exact scan.
|
|
458
|
+
*
|
|
459
|
+
* Indexes are only created when {@link dimensions} is at most 2000:
|
|
460
|
+
* pgvector cannot index a wider `vector` column, so a 3072-dimension
|
|
461
|
+
* embedding is left unindexed rather than failing the boot.
|
|
462
|
+
*/
|
|
463
|
+
index?: VectorIndexConfig | false;
|
|
410
464
|
validation?: PropertyValidationSchema;
|
|
411
465
|
}
|
|
412
466
|
|