@geekmidas/constructs 10.0.0-alpha.1 → 10.0.0-alpha.100

package/dist/external-api.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api.cjs","names":["canonicalId","provideKey","serviceKey","readCredentials","traceClient"],"sources":["../src/external-api.ts"],"sourcesContent":["/**\n * `ExternalApi` — an HTTP API somebody else runs.\n *\n * Polar, Stripe, a payment gateway: nothing to provision, but an address that\n * changes by stage and credentials the provider issued for each one. Without a\n * construct every integration writes that switching by hand — an optional\n * `POLAR_URL`, a fake started somewhere, a client built in a service — and the\n * target cannot see any of it.\n *\n * ```ts\n * // constructs/polar.ts\n * export const polar = new ExternalApi('Polar', {\n *   url: 'https://www.polaraccesslink.com',\n *   credentials: z.object({ clientId: z.string(), clientSecret: z.string() }),\n *   client: ({ url, credentials }) => new PolarClient(url, credentials),\n * });\n *\n * // test/fakes/polar.ts\n * export default fake.app(new Hono().post('/v3/oauth2/token', …), {\n *   credentials: { clientId: 'fake', clientSecret: 'fake' },\n * });\n *\n * // in a handler — the real API deployed, the fake locally and in tests\n * .dependsOn([polar])\n * .handle(({ services }) => services.polar.exchangeCode(code))\n * ```\n *\n * Deployed, the URL is `url` — one for every stage, or one per stage name with\n * a `default` — and the credentials are the stage's `<ID>_CREDENTIALS`, one\n * JSON value read the way a `Credential`'s is. Locally and in tests both come\n * from the fake.\n *\n * **The construct never names its fake.** It is found by convention, at\n * `test/fakes/<id>.ts`, and read only by gkm and the generated test harness —\n * so a fake, and the recorded responses it answers from, cannot end up in a\n * deployed bundle however the bundler follows imports.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\nimport { readCredentials } from './credential';\nimport type { DeployedStage, LocalStage } from './stages';\nimport { traceClient } from './tracing';\n\n/** What a credentials schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\n/**\n * Where an external API answers: one URL for every stage, or one per stage\n * name with `default` for any stage not listed.\n *\n * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,\n * so a key that names no stage — `prodution` — is a type error rather than a\n * URL nothing reads. Without the file any key goes, as before.\n */\nexport type ExternalApiUrl =\n\t| string\n\t| (string extends LocalStage | DeployedStage\n\t\t\t? Readonly<Record<string, string>>\n\t\t\t: { readonly [S in LocalStage | DeployedStage]?: string } & {\n\t\t\t\t\treadonly default?: string;\n\t\t\t\t});\n\nexport interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {\n\t/**\n\t * Where it answers deployed: one URL for every stage, or one per stage\n\t * name, with `default` for any stage not listed.\n\t */\n\turl: ExternalApiUrl;\n\t/** What the stage's `<ID>_CREDENTIALS` must look like. */\n\tcredentials: TSchema;\n\t/** What a handler is handed, built from where it answers and the credentials. */\n\tclient: (connection: {\n\t\turl: string;\n\t\tcredentials: Value<TSchema>;\n\t}) => TClient | Promise<TClient>;\n}\n\nexport class ExternalApi<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n\tTClient = unknown,\n> implements Consumable<TName, TClient>\n{\n\t// `Consumable` for the reason `Credential` gives: a client generic in\n\t// `TClient` cannot satisfy `Construct`'s conditional service type.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, TClient>;\n\n\t/** Read by both `declare()` and `connect()`, so the two cannot drift. */\n\tprivate readonly keys: { url: string; credentials: string };\n\n\t/** The promise, so concurrent registrations share one client. */\n\tprivate connected?: Promise<TClient>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: ExternalApiOptions<TSchema, TClient>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\tcredentials: provideKey(canonical, 'credentials'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => {\n\t\t\t\tthis.connected ??= this.connect(registerOptions);\n\t\t\t\treturn this.connected;\n\t\t\t},\n\t\t};\n\t}\n\n\t/**\n\t * What the stage's `<ID>_CREDENTIALS` must look like — the schema the value\n\t * is validated against where it is read. Public so a tool setting the value\n\t * (`gkm secrets:add`) can check it, and describe its fields, before it is\n\t * stored rather than at the first request.\n\t */\n\tget credentialsSchema(): TSchema {\n\t\treturn this.options.credentials;\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'external-api',\n\t\t\t\tid: this.id,\n\t\t\t\t// The stage-keyed map is a record of URLs to the manifest, which\n\t\t\t\t// reads it by whatever stage it is resolving.\n\t\t\t\turl: this.options.url as Readonly<Record<string, string>> | string,\n\t\t\t\tprovides: [this.keys.url, this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate async connect(options: ServiceRegisterOptions): Promise<TClient> {\n\t\tconst { url } = options.envParser\n\t\t\t.create((get) => ({ url: get(this.keys.url).string() }))\n\t\t\t.parse();\n\t\tconst credentials = await readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.credentials,\n\t\t\toptions.envParser,\n\t\t);\n\n\t\tconst client = await this.options.client({ url, credentials });\n\t\t// Each call a span carrying this API's name — the parent of the fetch\n\t\t// it makes, which is traced already.\n\t\treturn traceClient(this.id, client, {\n\t\t\t'server.address': hostOf(url),\n\t\t});\n\t}\n}\n\nfunction hostOf(url: string): string {\n\ttry {\n\t\treturn new URL(url).host;\n\t} catch {\n\t\treturn url;\n\t}\n}\n\n/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */\nexport interface FetchHandler {\n\tfetch(request: Request): Response | Promise<Response>;\n}\n\n/**\n * Marks a fake. A registered symbol, so a fake built by a second copy of this\n * package — a linked workspace, two versions in a lockfile — is still one.\n */\nconst FAKE = Symbol.for('@geekmidas/constructs/fake');\n\n/** What an external API's credentials look like going in, for a fake to supply. */\ntype CredentialsOf<TApi> =\n\tTApi extends ExternalApi<string, infer TSchema, unknown>\n\t\t? StandardSchemaV1.InferInput<TSchema>\n\t\t: unknown;\n\n/**\n * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.\n *\n * `credentials` are what the fake accepts, and what a local or test stage is\n * handed as `<ID>_CREDENTIALS` in place of the stage's own.\n */\nexport type Fake = {\n\treadonly [FAKE]: true;\n\treadonly credentials: unknown;\n} & (\n\t| {\n\t\t\treadonly kind: 'app';\n\t\t\t/** Served by gkm: in-process in a test, on its own port in `gkm dev`. */\n\t\t\treadonly handler: FetchHandler;\n\t  }\n\t| {\n\t\t\treadonly kind: 'image';\n\t\t\t/** The provider's own local server, run as a container. */\n\t\t\treadonly image: string;\n\t\t\t/** The port it listens on inside the container. */\n\t\t\treadonly port: number;\n\t  }\n);\n\n/**\n * Build the fake `test/fakes/<id>.ts` default-exports.\n *\n * Pass the API's type to have the credentials checked against its schema —\n * `fake.app<typeof polar>(…)`.\n */\nexport const fake = {\n\t/** A working implementation of the API, kept beside the tests that use it. */\n\tapp<TApi = unknown>(\n\t\thandler: FetchHandler,\n\t\toptions: { credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'app',\n\t\t\thandler,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n\n\t/** A local server the provider publishes — `stripe/stripe-mock`. */\n\timage<TApi = unknown>(\n\t\timage: string,\n\t\toptions: { port: number; credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'image',\n\t\t\timage,\n\t\t\tport: options.port,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n};\n\n/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */\nexport function isFake(value: unknown): value is Fake {\n\treturn (\n\t\ttypeof value === 'object' &&\n\t\tvalue !== null &&\n\t\t(value as { [FAKE]?: unknown })[FAKE] === true\n\t);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuFA,IAAa,cAAb,MAKA;CAcmB;CAXlB;CACA;;CAGA;;CAGA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,aAAA,GAAYA,oBAAAA,YAAAA,CAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO;GACX,MAAA,GAAKC,oBAAAA,WAAAA,CAAW,WAAW,KAAK;GAChC,cAAA,GAAaA,oBAAAA,WAAAA,CAAW,WAAW,aAAa;EACjD;EAGA,KAAK,UAAU;GACd,cAAA,GAAaC,oBAAAA,WAAAA,CAAW,SAAS;GACjC,WAAW,oBAAoB;IAC9B,KAAK,cAAc,KAAK,QAAQ,eAAe;IAC/C,OAAO,KAAK;GACb;EACD;CACD;;;;;;;CAQA,IAAI,oBAA6B;EAChC,OAAO,KAAK,QAAQ;CACrB;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GAGT,KAAK,KAAK,QAAQ;GAClB,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,WAAW;EAChD,CACD;CACD;CAEA,MAAc,QAAQ,SAAmD;EACxE,MAAM,EAAE,QAAQ,QAAQ,UACtB,QAAQ,SAAS,EAAE,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CACvD,MAAM;EACR,MAAM,cAAc,MAAMC,mBAAAA,gBACzB,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,aACb,QAAQ,SACT;EAEA,MAAM,SAAS,MAAM,KAAK,QAAQ,OAAO;GAAE;GAAK;EAAY,CAAC;EAG7D,OAAOC,gBAAAA,YAAY,KAAK,IAAI,QAAQ,EACnC,kBAAkB,OAAO,GAAG,EAC7B,CAAC;CACF;AACD;AAEA,SAAS,OAAO,KAAqB;CACpC,IAAI;EACH,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACrB,QAAQ;EACP,OAAO;CACR;AACD;;;;;AAWA,MAAM,OAAO,OAAO,IAAI,4BAA4B;;;;;;;AAsCpD,MAAa,OAAO;;CAEnB,IACC,SACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,aAAa,QAAQ;EACtB;CACD;;CAGA,MACC,OACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,MAAM,QAAQ;GACd,aAAa,QAAQ;EACtB;CACD;AACD;;AAGA,SAAgB,OAAO,OAA+B;CACrD,OACC,OAAO,UAAU,YACjB,UAAU,QACT,MAA+B,UAAU;AAE5C"}

package/dist/external-api.d.cts

@@ -0,0 +1,2 @@
+import { a as FetchHandler, i as Fake, n as ExternalApiOptions, o as fake, r as ExternalApiUrl, s as isFake, t as ExternalApi } from "./external-api-O107yzZJ.cjs";
+export { ExternalApi, ExternalApiOptions, ExternalApiUrl, Fake, FetchHandler, fake, isFake };

package/dist/external-api.d.mts

@@ -0,0 +1,2 @@
+import { a as FetchHandler, i as Fake, n as ExternalApiOptions, o as fake, r as ExternalApiUrl, s as isFake, t as ExternalApi } from "./external-api-MJ8id87V.mjs";
+export { ExternalApi, ExternalApiOptions, ExternalApiUrl, Fake, FetchHandler, fake, isFake };

package/dist/external-api.mjs

@@ -0,0 +1,139 @@
+import { readCredentials } from "./credential.mjs";
+import { r as traceClient } from "./tracing-CxaZ98IB.mjs";
+import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
+//#region src/external-api.ts
+/**
+* `ExternalApi` — an HTTP API somebody else runs.
+*
+* Polar, Stripe, a payment gateway: nothing to provision, but an address that
+* changes by stage and credentials the provider issued for each one. Without a
+* construct every integration writes that switching by hand — an optional
+* `POLAR_URL`, a fake started somewhere, a client built in a service — and the
+* target cannot see any of it.
+*
+* ```ts
+* // constructs/polar.ts
+* export const polar = new ExternalApi('Polar', {
+*   url: 'https://www.polaraccesslink.com',
+*   credentials: z.object({ clientId: z.string(), clientSecret: z.string() }),
+*   client: ({ url, credentials }) => new PolarClient(url, credentials),
+* });
+*
+* // test/fakes/polar.ts
+* export default fake.app(new Hono().post('/v3/oauth2/token', …), {
+*   credentials: { clientId: 'fake', clientSecret: 'fake' },
+* });
+*
+* // in a handler — the real API deployed, the fake locally and in tests
+* .dependsOn([polar])
+* .handle(({ services }) => services.polar.exchangeCode(code))
+* ```
+*
+* Deployed, the URL is `url` — one for every stage, or one per stage name with
+* a `default` — and the credentials are the stage's `<ID>_CREDENTIALS`, one
+* JSON value read the way a `Credential`'s is. Locally and in tests both come
+* from the fake.
+*
+* **The construct never names its fake.** It is found by convention, at
+* `test/fakes/<id>.ts`, and read only by gkm and the generated test harness —
+* so a fake, and the recorded responses it answers from, cannot end up in a
+* deployed bundle however the bundler follows imports.
+*/
+var ExternalApi = class {
+	options;
+	id;
+	service;
+	/** Read by both `declare()` and `connect()`, so the two cannot drift. */
+	keys;
+	/** The promise, so concurrent registrations share one client. */
+	connected;
+	constructor(id, options) {
+		this.options = options;
+		const canonical = canonicalId(id);
+		this.id = canonical;
+		this.keys = {
+			url: provideKey(canonical, "url"),
+			credentials: provideKey(canonical, "credentials")
+		};
+		this.service = {
+			serviceName: serviceKey(canonical),
+			register: (registerOptions) => {
+				this.connected ??= this.connect(registerOptions);
+				return this.connected;
+			}
+		};
+	}
+	/**
+	* What the stage's `<ID>_CREDENTIALS` must look like — the schema the value
+	* is validated against where it is read. Public so a tool setting the value
+	* (`gkm secrets:add`) can check it, and describe its fields, before it is
+	* stored rather than at the first request.
+	*/
+	get credentialsSchema() {
+		return this.options.credentials;
+	}
+	declare() {
+		return [{
+			kind: "external-api",
+			id: this.id,
+			url: this.options.url,
+			provides: [this.keys.url, this.keys.credentials]
+		}];
+	}
+	async connect(options) {
+		const { url } = options.envParser.create((get) => ({ url: get(this.keys.url).string() })).parse();
+		const credentials = await readCredentials(this.id, this.keys.credentials, this.options.credentials, options.envParser);
+		const client = await this.options.client({
+			url,
+			credentials
+		});
+		return traceClient(this.id, client, { "server.address": hostOf(url) });
+	}
+};
+function hostOf(url) {
+	try {
+		return new URL(url).host;
+	} catch {
+		return url;
+	}
+}
+/**
+* Marks a fake. A registered symbol, so a fake built by a second copy of this
+* package — a linked workspace, two versions in a lockfile — is still one.
+*/
+const FAKE = Symbol.for("@geekmidas/constructs/fake");
+/**
+* Build the fake `test/fakes/<id>.ts` default-exports.
+*
+* Pass the API's type to have the credentials checked against its schema —
+* `fake.app<typeof polar>(…)`.
+*/
+const fake = {
+	/** A working implementation of the API, kept beside the tests that use it. */
+	app(handler, options) {
+		return {
+			[FAKE]: true,
+			kind: "app",
+			handler,
+			credentials: options.credentials
+		};
+	},
+	/** A local server the provider publishes — `stripe/stripe-mock`. */
+	image(image, options) {
+		return {
+			[FAKE]: true,
+			kind: "image",
+			image,
+			port: options.port,
+			credentials: options.credentials
+		};
+	}
+};
+/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */
+function isFake(value) {
+	return typeof value === "object" && value !== null && value[FAKE] === true;
+}
+//#endregion
+export { ExternalApi, fake, isFake };
+
+//# sourceMappingURL=external-api.mjs.map

package/dist/external-api.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"external-api.mjs","names":[],"sources":["../src/external-api.ts"],"sourcesContent":["/**\n * `ExternalApi` — an HTTP API somebody else runs.\n *\n * Polar, Stripe, a payment gateway: nothing to provision, but an address that\n * changes by stage and credentials the provider issued for each one. Without a\n * construct every integration writes that switching by hand — an optional\n * `POLAR_URL`, a fake started somewhere, a client built in a service — and the\n * target cannot see any of it.\n *\n * ```ts\n * // constructs/polar.ts\n * export const polar = new ExternalApi('Polar', {\n *   url: 'https://www.polaraccesslink.com',\n *   credentials: z.object({ clientId: z.string(), clientSecret: z.string() }),\n *   client: ({ url, credentials }) => new PolarClient(url, credentials),\n * });\n *\n * // test/fakes/polar.ts\n * export default fake.app(new Hono().post('/v3/oauth2/token', …), {\n *   credentials: { clientId: 'fake', clientSecret: 'fake' },\n * });\n *\n * // in a handler — the real API deployed, the fake locally and in tests\n * .dependsOn([polar])\n * .handle(({ services }) => services.polar.exchangeCode(code))\n * ```\n *\n * Deployed, the URL is `url` — one for every stage, or one per stage name with\n * a `default` — and the credentials are the stage's `<ID>_CREDENTIALS`, one\n * JSON value read the way a `Credential`'s is. Locally and in tests both come\n * from the fake.\n *\n * **The construct never names its fake.** It is found by convention, at\n * `test/fakes/<id>.ts`, and read only by gkm and the generated test harness —\n * so a fake, and the recorded responses it answers from, cannot end up in a\n * deployed bundle however the bundler follows imports.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { Consumable } from './construct-interface';\nimport { readCredentials } from './credential';\nimport type { DeployedStage, LocalStage } from './stages';\nimport { traceClient } from './tracing';\n\n/** What a credentials schema yields. */\ntype Value<TSchema extends StandardSchemaV1> =\n\tStandardSchemaV1.InferOutput<TSchema>;\n\n/**\n * Where an external API answers: one URL for every stage, or one per stage\n * name with `default` for any stage not listed.\n *\n * Keyed by the stages `gkm.config.ts` declares once `.gkm/stages.d.ts` exists,\n * so a key that names no stage — `prodution` — is a type error rather than a\n * URL nothing reads. Without the file any key goes, as before.\n */\nexport type ExternalApiUrl =\n\t| string\n\t| (string extends LocalStage | DeployedStage\n\t\t\t? Readonly<Record<string, string>>\n\t\t\t: { readonly [S in LocalStage | DeployedStage]?: string } & {\n\t\t\t\t\treadonly default?: string;\n\t\t\t\t});\n\nexport interface ExternalApiOptions<TSchema extends StandardSchemaV1, TClient> {\n\t/**\n\t * Where it answers deployed: one URL for every stage, or one per stage\n\t * name, with `default` for any stage not listed.\n\t */\n\turl: ExternalApiUrl;\n\t/** What the stage's `<ID>_CREDENTIALS` must look like. */\n\tcredentials: TSchema;\n\t/** What a handler is handed, built from where it answers and the credentials. */\n\tclient: (connection: {\n\t\turl: string;\n\t\tcredentials: Value<TSchema>;\n\t}) => TClient | Promise<TClient>;\n}\n\nexport class ExternalApi<\n\tTName extends string = string,\n\tTSchema extends StandardSchemaV1 = StandardSchemaV1,\n\tTClient = unknown,\n> implements Consumable<TName, TClient>\n{\n\t// `Consumable` for the reason `Credential` gives: a client generic in\n\t// `TClient` cannot satisfy `Construct`'s conditional service type.\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, TClient>;\n\n\t/** Read by both `declare()` and `connect()`, so the two cannot drift. */\n\tprivate readonly keys: { url: string; credentials: string };\n\n\t/** The promise, so concurrent registrations share one client. */\n\tprivate connected?: Promise<TClient>;\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: ExternalApiOptions<TSchema, TClient>,\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.keys = {\n\t\t\turl: provideKey(canonical, 'url'),\n\t\t\tcredentials: provideKey(canonical, 'credentials'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => {\n\t\t\t\tthis.connected ??= this.connect(registerOptions);\n\t\t\t\treturn this.connected;\n\t\t\t},\n\t\t};\n\t}\n\n\t/**\n\t * What the stage's `<ID>_CREDENTIALS` must look like — the schema the value\n\t * is validated against where it is read. Public so a tool setting the value\n\t * (`gkm secrets:add`) can check it, and describe its fields, before it is\n\t * stored rather than at the first request.\n\t */\n\tget credentialsSchema(): TSchema {\n\t\treturn this.options.credentials;\n\t}\n\n\tdeclare(): Declaration[] {\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'external-api',\n\t\t\t\tid: this.id,\n\t\t\t\t// The stage-keyed map is a record of URLs to the manifest, which\n\t\t\t\t// reads it by whatever stage it is resolving.\n\t\t\t\turl: this.options.url as Readonly<Record<string, string>> | string,\n\t\t\t\tprovides: [this.keys.url, this.keys.credentials],\n\t\t\t},\n\t\t];\n\t}\n\n\tprivate async connect(options: ServiceRegisterOptions): Promise<TClient> {\n\t\tconst { url } = options.envParser\n\t\t\t.create((get) => ({ url: get(this.keys.url).string() }))\n\t\t\t.parse();\n\t\tconst credentials = await readCredentials(\n\t\t\tthis.id,\n\t\t\tthis.keys.credentials,\n\t\t\tthis.options.credentials,\n\t\t\toptions.envParser,\n\t\t);\n\n\t\tconst client = await this.options.client({ url, credentials });\n\t\t// Each call a span carrying this API's name — the parent of the fetch\n\t\t// it makes, which is traced already.\n\t\treturn traceClient(this.id, client, {\n\t\t\t'server.address': hostOf(url),\n\t\t});\n\t}\n}\n\nfunction hostOf(url: string): string {\n\ttry {\n\t\treturn new URL(url).host;\n\t} catch {\n\t\treturn url;\n\t}\n}\n\n/** Anything that answers a request — a Hono app, or a bare `{ fetch }`. */\nexport interface FetchHandler {\n\tfetch(request: Request): Response | Promise<Response>;\n}\n\n/**\n * Marks a fake. A registered symbol, so a fake built by a second copy of this\n * package — a linked workspace, two versions in a lockfile — is still one.\n */\nconst FAKE = Symbol.for('@geekmidas/constructs/fake');\n\n/** What an external API's credentials look like going in, for a fake to supply. */\ntype CredentialsOf<TApi> =\n\tTApi extends ExternalApi<string, infer TSchema, unknown>\n\t\t? StandardSchemaV1.InferInput<TSchema>\n\t\t: unknown;\n\n/**\n * An external API's stand-in, as `test/fakes/<id>.ts` default-exports it.\n *\n * `credentials` are what the fake accepts, and what a local or test stage is\n * handed as `<ID>_CREDENTIALS` in place of the stage's own.\n */\nexport type Fake = {\n\treadonly [FAKE]: true;\n\treadonly credentials: unknown;\n} & (\n\t| {\n\t\t\treadonly kind: 'app';\n\t\t\t/** Served by gkm: in-process in a test, on its own port in `gkm dev`. */\n\t\t\treadonly handler: FetchHandler;\n\t  }\n\t| {\n\t\t\treadonly kind: 'image';\n\t\t\t/** The provider's own local server, run as a container. */\n\t\t\treadonly image: string;\n\t\t\t/** The port it listens on inside the container. */\n\t\t\treadonly port: number;\n\t  }\n);\n\n/**\n * Build the fake `test/fakes/<id>.ts` default-exports.\n *\n * Pass the API's type to have the credentials checked against its schema —\n * `fake.app<typeof polar>(…)`.\n */\nexport const fake = {\n\t/** A working implementation of the API, kept beside the tests that use it. */\n\tapp<TApi = unknown>(\n\t\thandler: FetchHandler,\n\t\toptions: { credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'app',\n\t\t\thandler,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n\n\t/** A local server the provider publishes — `stripe/stripe-mock`. */\n\timage<TApi = unknown>(\n\t\timage: string,\n\t\toptions: { port: number; credentials: CredentialsOf<TApi> },\n\t): Fake {\n\t\treturn {\n\t\t\t[FAKE]: true,\n\t\t\tkind: 'image',\n\t\t\timage,\n\t\t\tport: options.port,\n\t\t\tcredentials: options.credentials,\n\t\t};\n\t},\n};\n\n/** Whether a value is a fake — what gkm asks of a `test/fakes` default export. */\nexport function isFake(value: unknown): value is Fake {\n\treturn (\n\t\ttypeof value === 'object' &&\n\t\tvalue !== null &&\n\t\t(value as { [FAKE]?: unknown })[FAKE] === true\n\t);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuFA,IAAa,cAAb,MAKA;CAcmB;CAXlB;CACA;;CAGA;;CAGA;CAEA,YACC,IACA,SACC;EADgB,KAAA,UAAA;EAEjB,MAAM,YAAY,YAAY,EAAY;EAE1C,KAAK,KAAK;EACV,KAAK,OAAO;GACX,KAAK,WAAW,WAAW,KAAK;GAChC,aAAa,WAAW,WAAW,aAAa;EACjD;EAGA,KAAK,UAAU;GACd,aAAa,WAAW,SAAS;GACjC,WAAW,oBAAoB;IAC9B,KAAK,cAAc,KAAK,QAAQ,eAAe;IAC/C,OAAO,KAAK;GACb;EACD;CACD;;;;;;;CAQA,IAAI,oBAA6B;EAChC,OAAO,KAAK,QAAQ;CACrB;CAEA,UAAyB;EACxB,OAAO,CACN;GACC,MAAM;GACN,IAAI,KAAK;GAGT,KAAK,KAAK,QAAQ;GAClB,UAAU,CAAC,KAAK,KAAK,KAAK,KAAK,KAAK,WAAW;EAChD,CACD;CACD;CAEA,MAAc,QAAQ,SAAmD;EACxE,MAAM,EAAE,QAAQ,QAAQ,UACtB,QAAQ,SAAS,EAAE,KAAK,IAAI,KAAK,KAAK,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CACvD,MAAM;EACR,MAAM,cAAc,MAAM,gBACzB,KAAK,IACL,KAAK,KAAK,aACV,KAAK,QAAQ,aACb,QAAQ,SACT;EAEA,MAAM,SAAS,MAAM,KAAK,QAAQ,OAAO;GAAE;GAAK;EAAY,CAAC;EAG7D,OAAO,YAAY,KAAK,IAAI,QAAQ,EACnC,kBAAkB,OAAO,GAAG,EAC7B,CAAC;CACF;AACD;AAEA,SAAS,OAAO,KAAqB;CACpC,IAAI;EACH,OAAO,IAAI,IAAI,GAAG,CAAC,CAAC;CACrB,QAAQ;EACP,OAAO;CACR;AACD;;;;;AAWA,MAAM,OAAO,OAAO,IAAI,4BAA4B;;;;;;;AAsCpD,MAAa,OAAO;;CAEnB,IACC,SACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,aAAa,QAAQ;EACtB;CACD;;CAGA,MACC,OACA,SACO;EACP,OAAO;IACL,OAAO;GACR,MAAM;GACN;GACA,MAAM,QAAQ;GACd,aAAa,QAAQ;EACtB;CACD;AACD;;AAGA,SAAgB,OAAO,OAA+B;CACrD,OACC,OAAO,UAAU,YACjB,UAAU,QACT,MAA+B,UAAU;AAE5C"}

package/dist/file-server.cjs

@@ -1,10 +1,41 @@
-const require_chunk = require('./chunk-DWy1uDak.cjs');
-const __geekmidas_manifest = require_chunk.__toESM(require("@geekmidas/manifest"));
-const __geekmidas_storage = require_chunk.__toESM(require("@geekmidas/storage"));
-
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _geekmidas_manifest = require("@geekmidas/manifest");
+let _geekmidas_storage = require("@geekmidas/storage");
 //#region src/file-server.ts
+/**
+* `FileServer` — a domain that serves a bucket's objects.
+*
+* `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never
+* public. Serving those objects on a domain is a different thing, and it is a
+* construct of its own rather than a flag on the bucket — see
+* `docs/design/constructs-paradigm.md`, "Why a separate construct, and what it
+* costs", for the comparison that rules the other two shapes out.
+*
+* ```ts
+* export const uploads = new FileServer('Uploads', { open: ['brand/**'] });
+*
+* uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket
+* uploads.url('brand/logo.png')                // open path — no signature
+* uploads.signedUrl('invoices/7.pdf')          // one object, one recipient
+* ```
+*
+* **One construct, one client, both halves.** How a file lands in the bucket is
+* the same whether or not it is served, so splitting the upload half from the
+* serving half would be ceremony rather than safety. The client is a *superset*
+* of `StorageClient`, made literal in the type, so anything taking
+* `services.uploads` keeps compiling when the construct behind it grows a
+* serving half.
+*
+* **The id names the bucket, not the surface.** This is the detail that has to
+* be right before anything ships, because getting it backwards is destructive:
+* the migration people actually perform is serving a bucket they already have,
+* and naming the bucket after the construct makes that edit *add* a node rather
+* than rename the one holding the data.
+*/
 /** A key was asked to be served unsigned, and no open pattern admits it. */
 var NotOpen = class extends Error {
+	key;
+	open;
 	constructor(key, open) {
 		super(`'${key}' is not served without a signature. ` + (open.length ? `Open paths: ${open.join(", ")}. Use signedUrl() for anything else.` : "This file server declares no open paths, so every object needs signedUrl()."));
 		this.key = key;
@@ -13,6 +44,7 @@ var NotOpen = class extends Error {
 	}
 };
 var FileServer = class {
+	options;
 	id;
 	service;
 	/** The id of the surface node, as opposed to the bucket's. */
@@ -25,17 +57,17 @@ var FileServer = class {
 	keys;
 	constructor(id, options = {}) {
 		this.options = options;
-		const canonical = (0, __geekmidas_manifest.canonicalId)(id);
+		const canonical = (0, _geekmidas_manifest.canonicalId)(id);
 		this.id = canonical;
 		this.open = options.open ?? [];
 		const originId = options.origin?.id ?? canonical;
 		this.surfaceId = `${canonical}Server`;
 		this.keys = {
-			origin: (0, __geekmidas_manifest.provideKey)(originId, "url"),
-			server: (0, __geekmidas_manifest.provideKey)(this.surfaceId, "url")
+			origin: (0, _geekmidas_manifest.provideKey)(originId, "url"),
+			server: (0, _geekmidas_manifest.provideKey)(this.surfaceId, "url")
 		};
 		this.service = {
-			serviceName: (0, __geekmidas_manifest.serviceKey)(canonical),
+			serviceName: (0, _geekmidas_manifest.serviceKey)(canonical),
 			register: (registerOptions) => this.connect(registerOptions)
 		};
 	}
@@ -99,7 +131,7 @@ var FileServer = class {
 			origin: get(this.keys.origin).string(),
 			server: get(this.keys.server).string()
 		})).parse();
-		const storage = (0, __geekmidas_storage.createStorageClient)(origin);
+		const storage = (0, _geekmidas_storage.createStorageClient)(origin);
 		const base = server.replace(/\/+$/, "");
 		const serve = (key) => {
 			if (!this.serves(key)) throw new NotOpen(key, this.open);
@@ -147,8 +179,8 @@ function globToRegExp(pattern) {
 	}
 	return new RegExp(`^${source}$`);
 }
-
 //#endregion
 exports.FileServer = FileServer;
 exports.NotOpen = NotOpen;
+
 //# sourceMappingURL=file-server.cjs.map

package/dist/file-server.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"file-server.cjs","names":["key: string","open: readonly string[]","id: ConstructName<TName>","options: FileServerOptions<TOpen>","surface: Declaration","options: ServiceRegisterOptions","expiresIn?: number","pattern: string"],"sources":["../src/file-server.ts"],"sourcesContent":["/**\n * `FileServer` — a domain that serves a bucket's objects.\n *\n * `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never\n * public. Serving those objects on a domain is a different thing, and it is a\n * construct of its own rather than a flag on the bucket — see\n * `docs/design/constructs-paradigm.md`, \"Why a separate construct, and what it\n * costs\", for the comparison that rules the other two shapes out.\n *\n * ```ts\n * export const uploads = new FileServer('Uploads', { open: ['brand/**'] });\n *\n * uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket\n * uploads.url('brand/logo.png')                // open path — no signature\n * uploads.signedUrl('invoices/7.pdf')          // one object, one recipient\n * ```\n *\n * **One construct, one client, both halves.** How a file lands in the bucket is\n * the same whether or not it is served, so splitting the upload half from the\n * serving half would be ceremony rather than safety. The client is a *superset*\n * of `StorageClient`, made literal in the type, so anything taking\n * `services.uploads` keeps compiling when the construct behind it grows a\n * serving half.\n *\n * **The id names the bucket, not the surface.** This is the detail that has to\n * be right before anything ships, because getting it backwards is destructive:\n * the migration people actually perform is serving a bucket they already have,\n * and naming the bucket after the construct makes that edit *add* a node rather\n * than rename the one holding the data.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport { createStorageClient, type StorageClient } from '@geekmidas/storage';\nimport type { Construct, Declarable } from './construct-interface';\n\n/**\n * A key an open pattern admits.\n *\n * The same template-literal trick `ConstructName` uses, so `open` is checked at\n * the call site rather than only at the edge:\n *\n * ```ts\n * files.url('brand/logo.png')       // ok\n * files.url(`avatars/${id}.png`)    // ok — a template literal still matches\n * files.url('invoices/7.pdf')       // not assignable — never served unsigned\n * ```\n *\n * A single star and a double star resolve to the same type, stated rather than\n * discovered: a template literal cannot exclude `/`, so this is a prefix-and-\n * suffix guard while the *exact* pattern is enforced by the bucket policy, by\n * the cache behaviour, and by this construct's own runtime check. The type says\n * plausibly open; the infrastructure says definitely.\n */\nexport type Served<P extends string> = P extends `${infer Head}**`\n\t? `${Head}${string}`\n\t: P extends `${infer Head}*${infer Tail}`\n\t\t? `${Head}${string}${Tail}`\n\t\t: P;\n\n/** What consuming a file server hands you: a bucket client that also serves. */\nexport interface FileServerClient<TOpen extends string = never>\n\textends StorageClient {\n\t/**\n\t * The unsigned address of an open object.\n\t *\n\t * Compile-checked against the declared patterns, *and* checked again at\n\t * runtime — a JavaScript caller gets no compiler, and minting an unsigned\n\t * URL for a private object is a leak rather than a mistake.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\turl(key: Served<TOpen>): string;\n\n\t/**\n\t * The same thing for a key the compiler cannot see.\n\t *\n\t * A fully dynamic key does not type, which is correct and is also the case\n\t * people will hit — so the escape hatch is a named method rather than a\n\t * cast, and it runs the *same* runtime check rather than being a way around\n\t * it.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\topenUrl(key: string): string;\n\n\t/**\n\t * A signed address for one object and one recipient.\n\t *\n\t * Today this is an **S3 presign at the bucket**, which is what works\n\t * unchanged against MinIO locally and against S3 deployed. It is deliberately\n\t * not described as a CDN URL: CloudFront signing is a different mechanism,\n\t * with different keys, against a different host, and it needs key material\n\t * this construct does not yet declare.\n\t *\n\t * @param expiresIn - minutes, matching `getUploadURL`.\n\t */\n\tsignedUrl(key: string, expiresIn?: number): Promise<string>;\n}\n\nexport interface FileServerOptions<TOpen extends string = never> {\n\t/**\n\t * Paths served without a signature. Everything else needs one.\n\t *\n\t * Private by default: a bucket where forgetting a flag publishes user\n\t * uploads is the wrong default, so this is an exception list, and listing it\n\t * in code means exactly one set of paths is unauthenticated and it is\n\t * reviewable in a diff.\n\t *\n\t * Uploading is deliberately *not* restricted to these. Writing to a path\n\t * that happens to be open is ordinary; the only asymmetry worth enforcing is\n\t * that you cannot hand out an unsigned URL for something the server would\n\t * refuse to serve unsigned.\n\t */\n\topen?: readonly TOpen[];\n\t/** Keep previous versions of an object. */\n\tversioned?: boolean;\n\t/**\n\t * A bucket declared elsewhere, instead of one of this server's own.\n\t *\n\t * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that\n\t * already exists, which is also how the two edges come back when you want\n\t * them separately — a handler depending on the bucket writes, a handler\n\t * depending on the server mints URLs.\n\t */\n\torigin?: Declarable;\n}\n\n/** A key was asked to be served unsigned, and no open pattern admits it. */\nexport class NotOpen extends Error {\n\tconstructor(\n\t\treadonly key: string,\n\t\treadonly open: readonly string[],\n\t) {\n\t\tsuper(\n\t\t\t`'${key}' is not served without a signature. ` +\n\t\t\t\t(open.length\n\t\t\t\t\t? `Open paths: ${open.join(', ')}. Use signedUrl() for anything else.`\n\t\t\t\t\t: 'This file server declares no open paths, so every object needs signedUrl().'),\n\t\t);\n\t\tthis.name = 'NotOpen';\n\t}\n}\n\nexport class FileServer<\n\tTName extends string = string,\n\tTOpen extends string = never,\n> implements Construct<TName, FileServerClient<TOpen>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;\n\n\t/** The id of the surface node, as opposed to the bucket's. */\n\treadonly surfaceId: string;\n\n\tprivate readonly open: readonly string[];\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the keys the\n\t * target publishes and the keys the client reads cannot drift.\n\t */\n\tprivate readonly keys: { origin: string; server: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: FileServerOptions<TOpen> = {},\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.open = options.open ?? [];\n\n\t\t// The surface takes the suffix and the bucket keeps the plain id, which\n\t\t// is what makes \"serve a bucket I already have\" an edit that adds a node\n\t\t// instead of renaming the one holding the data.\n\t\tconst originId = options.origin?.id ?? canonical;\n\t\tthis.surfaceId = `${canonical}Server`;\n\n\t\tthis.keys = {\n\t\t\torigin: provideKey(originId, 'url'),\n\t\t\tserver: provideKey(this.surfaceId, 'url'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\t/**\n\t * The served surface, as something an edge can point at.\n\t *\n\t * Depending on the `FileServer` itself points at the **bucket** — its\n\t * canonical node — which is right for a handler: it presigns and writes. But\n\t * a bucket's URL is never public, so a site depending on it gets nothing\n\t * inlined, which is correct and also useless.\n\t *\n\t * This is the other half: `.dependsOn([uploads.server])` points at the\n\t * surface, whose address *is* public, and is what puts\n\t * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape\n\t * `database.reader()` uses, and for the same reason — one construct owning\n\t * two addresses needs a way to name the second.\n\t */\n\tget server(): Declarable {\n\t\tconst surface = this.declare().find(\n\t\t\t(declaration) => declaration.id === this.surfaceId,\n\t\t);\n\n\t\treturn {\n\t\t\tid: this.surfaceId,\n\t\t\tdeclare: () => (surface ? [surface] : []),\n\t\t};\n\t}\n\n\t/**\n\t * The bucket and the surface over it — or just the surface, when the bucket\n\t * was declared elsewhere.\n\t *\n\t * The surface names its origin through `of`, which is what makes the\n\t * reference check work: an origin resolving to nothing is a build failure,\n\t * the same guarantee `assertDerivations` already gives a reader and a schema\n\t * tenant.\n\t */\n\tdeclare(): Declaration[] {\n\t\tconst origin = this.options.origin;\n\n\t\tconst surface: Declaration = {\n\t\t\tkind: 'file-server',\n\t\t\tid: this.surfaceId,\n\t\t\tof: origin?.id ?? this.id,\n\t\t\t...(this.open.length ? { open: this.open } : {}),\n\t\t\tprovides: [this.keys.server],\n\t\t};\n\n\t\t// A vended bucket is declared here; a given one already declares itself,\n\t\t// and declaring it twice is the duplication the whole model removes.\n\t\tif (origin) return [surface];\n\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'objects',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.origin],\n\t\t\t\t...(this.options.versioned ? { versioned: true } : {}),\n\t\t\t},\n\t\t\tsurface,\n\t\t];\n\t}\n\n\t/**\n\t * The bucket's client, with the serving half added.\n\t *\n\t * Both addresses are read here, which is also how the environment reaches a\n\t * handler: the sniffer records what this reads, so `.dependsOn([uploads])`\n\t * carries the bucket URL and the server URL without either being written\n\t * down beside the handler.\n\t */\n\tprivate async connect(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<FileServerClient<TOpen>> {\n\t\tconst { origin, server } = options.envParser\n\t\t\t.create((get) => ({\n\t\t\t\torigin: get(this.keys.origin).string(),\n\t\t\t\tserver: get(this.keys.server).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\tconst storage = createStorageClient(origin);\n\t\tconst base = server.replace(/\\/+$/, '');\n\n\t\tconst serve = (key: string): string => {\n\t\t\tif (!this.serves(key)) throw new NotOpen(key, this.open);\n\n\t\t\treturn `${base}/${key.replace(/^\\/+/, '')}`;\n\t\t};\n\n\t\t// Delegating rather than copying: the bucket half is whatever the driver\n\t\t// produced, including anything it grows later, and only the serving half\n\t\t// is added on top.\n\t\treturn Object.assign(Object.create(storage) as StorageClient, {\n\t\t\turl: serve as (key: Served<TOpen>) => string,\n\t\t\topenUrl: serve,\n\t\t\tsignedUrl: (key: string, expiresIn?: number) =>\n\t\t\t\tstorage.getDownloadURL({ path: key } as never, expiresIn),\n\t\t}) as FileServerClient<TOpen>;\n\t}\n\n\t/**\n\t * Whether an open pattern admits a key.\n\t *\n\t * The runtime half of {@link Served}, and stricter than it: here a single\n\t * star stops at a segment boundary and a double star does not, which is the\n\t * distinction a template-literal type cannot draw and the infrastructure\n\t * does.\n\t */\n\tprivate serves(key: string): boolean {\n\t\treturn this.open.some((pattern) => globToRegExp(pattern).test(key));\n\t}\n}\n\n/**\n * One open pattern as an anchored expression.\n *\n * A double star crosses `/`; a single star does not. Both are consumed in one\n * left-to-right pass rather than by substitution, so a pattern cannot be\n * rewritten into a placeholder that a later pass mistakes for literal text.\n */\nfunction globToRegExp(pattern: string): RegExp {\n\tlet source = '';\n\n\tfor (let index = 0; index < pattern.length; index++) {\n\t\tconst character = pattern[index];\n\n\t\tif (character !== '*') {\n\t\t\tsource += character?.replace(/[.+^${}()|[\\]\\\\?]/, '\\\\$&') ?? '';\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (pattern[index + 1] === '*') {\n\t\t\tsource += '.*';\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tsource += '[^/]*';\n\t}\n\n\treturn new RegExp(`^${source}$`);\n}\n"],"mappings":"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"}
+{"version":3,"file":"file-server.cjs","names":["canonicalId","provideKey","serviceKey","createStorageClient"],"sources":["../src/file-server.ts"],"sourcesContent":["/**\n * `FileServer` — a domain that serves a bucket's objects.\n *\n * `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never\n * public. Serving those objects on a domain is a different thing, and it is a\n * construct of its own rather than a flag on the bucket — see\n * `docs/design/constructs-paradigm.md`, \"Why a separate construct, and what it\n * costs\", for the comparison that rules the other two shapes out.\n *\n * ```ts\n * export const uploads = new FileServer('Uploads', { open: ['brand/**'] });\n *\n * uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket\n * uploads.url('brand/logo.png')                // open path — no signature\n * uploads.signedUrl('invoices/7.pdf')          // one object, one recipient\n * ```\n *\n * **One construct, one client, both halves.** How a file lands in the bucket is\n * the same whether or not it is served, so splitting the upload half from the\n * serving half would be ceremony rather than safety. The client is a *superset*\n * of `StorageClient`, made literal in the type, so anything taking\n * `services.uploads` keeps compiling when the construct behind it grows a\n * serving half.\n *\n * **The id names the bucket, not the surface.** This is the detail that has to\n * be right before anything ships, because getting it backwards is destructive:\n * the migration people actually perform is serving a bucket they already have,\n * and naming the bucket after the construct makes that edit *add* a node rather\n * than rename the one holding the data.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport { createStorageClient, type StorageClient } from '@geekmidas/storage';\nimport type { Construct, Declarable } from './construct-interface';\n\n/**\n * A key an open pattern admits.\n *\n * The same template-literal trick `ConstructName` uses, so `open` is checked at\n * the call site rather than only at the edge:\n *\n * ```ts\n * files.url('brand/logo.png')       // ok\n * files.url(`avatars/${id}.png`)    // ok — a template literal still matches\n * files.url('invoices/7.pdf')       // not assignable — never served unsigned\n * ```\n *\n * A single star and a double star resolve to the same type, stated rather than\n * discovered: a template literal cannot exclude `/`, so this is a prefix-and-\n * suffix guard while the *exact* pattern is enforced by the bucket policy, by\n * the cache behaviour, and by this construct's own runtime check. The type says\n * plausibly open; the infrastructure says definitely.\n */\nexport type Served<P extends string> = P extends `${infer Head}**`\n\t? `${Head}${string}`\n\t: P extends `${infer Head}*${infer Tail}`\n\t\t? `${Head}${string}${Tail}`\n\t\t: P;\n\n/** What consuming a file server hands you: a bucket client that also serves. */\nexport interface FileServerClient<TOpen extends string = never>\n\textends StorageClient {\n\t/**\n\t * The unsigned address of an open object.\n\t *\n\t * Compile-checked against the declared patterns, *and* checked again at\n\t * runtime — a JavaScript caller gets no compiler, and minting an unsigned\n\t * URL for a private object is a leak rather than a mistake.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\turl(key: Served<TOpen>): string;\n\n\t/**\n\t * The same thing for a key the compiler cannot see.\n\t *\n\t * A fully dynamic key does not type, which is correct and is also the case\n\t * people will hit — so the escape hatch is a named method rather than a\n\t * cast, and it runs the *same* runtime check rather than being a way around\n\t * it.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\topenUrl(key: string): string;\n\n\t/**\n\t * A signed address for one object and one recipient.\n\t *\n\t * Today this is an **S3 presign at the bucket**, which is what works\n\t * unchanged against MinIO locally and against S3 deployed. It is deliberately\n\t * not described as a CDN URL: CloudFront signing is a different mechanism,\n\t * with different keys, against a different host, and it needs key material\n\t * this construct does not yet declare.\n\t *\n\t * @param expiresIn - minutes, matching `getUploadURL`.\n\t */\n\tsignedUrl(key: string, expiresIn?: number): Promise<string>;\n}\n\nexport interface FileServerOptions<TOpen extends string = never> {\n\t/**\n\t * Paths served without a signature. Everything else needs one.\n\t *\n\t * Private by default: a bucket where forgetting a flag publishes user\n\t * uploads is the wrong default, so this is an exception list, and listing it\n\t * in code means exactly one set of paths is unauthenticated and it is\n\t * reviewable in a diff.\n\t *\n\t * Uploading is deliberately *not* restricted to these. Writing to a path\n\t * that happens to be open is ordinary; the only asymmetry worth enforcing is\n\t * that you cannot hand out an unsigned URL for something the server would\n\t * refuse to serve unsigned.\n\t */\n\topen?: readonly TOpen[];\n\t/** Keep previous versions of an object. */\n\tversioned?: boolean;\n\t/**\n\t * A bucket declared elsewhere, instead of one of this server's own.\n\t *\n\t * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that\n\t * already exists, which is also how the two edges come back when you want\n\t * them separately — a handler depending on the bucket writes, a handler\n\t * depending on the server mints URLs.\n\t */\n\torigin?: Declarable;\n}\n\n/** A key was asked to be served unsigned, and no open pattern admits it. */\nexport class NotOpen extends Error {\n\tconstructor(\n\t\treadonly key: string,\n\t\treadonly open: readonly string[],\n\t) {\n\t\tsuper(\n\t\t\t`'${key}' is not served without a signature. ` +\n\t\t\t\t(open.length\n\t\t\t\t\t? `Open paths: ${open.join(', ')}. Use signedUrl() for anything else.`\n\t\t\t\t\t: 'This file server declares no open paths, so every object needs signedUrl().'),\n\t\t);\n\t\tthis.name = 'NotOpen';\n\t}\n}\n\nexport class FileServer<\n\tTName extends string = string,\n\tTOpen extends string = never,\n> implements Construct<TName, FileServerClient<TOpen>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;\n\n\t/** The id of the surface node, as opposed to the bucket's. */\n\treadonly surfaceId: string;\n\n\tprivate readonly open: readonly string[];\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the keys the\n\t * target publishes and the keys the client reads cannot drift.\n\t */\n\tprivate readonly keys: { origin: string; server: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: FileServerOptions<TOpen> = {},\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.open = options.open ?? [];\n\n\t\t// The surface takes the suffix and the bucket keeps the plain id, which\n\t\t// is what makes \"serve a bucket I already have\" an edit that adds a node\n\t\t// instead of renaming the one holding the data.\n\t\tconst originId = options.origin?.id ?? canonical;\n\t\tthis.surfaceId = `${canonical}Server`;\n\n\t\tthis.keys = {\n\t\t\torigin: provideKey(originId, 'url'),\n\t\t\tserver: provideKey(this.surfaceId, 'url'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\t/**\n\t * The served surface, as something an edge can point at.\n\t *\n\t * Depending on the `FileServer` itself points at the **bucket** — its\n\t * canonical node — which is right for a handler: it presigns and writes. But\n\t * a bucket's URL is never public, so a site depending on it gets nothing\n\t * inlined, which is correct and also useless.\n\t *\n\t * This is the other half: `.dependsOn([uploads.server])` points at the\n\t * surface, whose address *is* public, and is what puts\n\t * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape\n\t * `database.reader()` uses, and for the same reason — one construct owning\n\t * two addresses needs a way to name the second.\n\t */\n\tget server(): Declarable {\n\t\tconst surface = this.declare().find(\n\t\t\t(declaration) => declaration.id === this.surfaceId,\n\t\t);\n\n\t\treturn {\n\t\t\tid: this.surfaceId,\n\t\t\tdeclare: () => (surface ? [surface] : []),\n\t\t};\n\t}\n\n\t/**\n\t * The bucket and the surface over it — or just the surface, when the bucket\n\t * was declared elsewhere.\n\t *\n\t * The surface names its origin through `of`, which is what makes the\n\t * reference check work: an origin resolving to nothing is a build failure,\n\t * the same guarantee `assertDerivations` already gives a reader and a schema\n\t * tenant.\n\t */\n\tdeclare(): Declaration[] {\n\t\tconst origin = this.options.origin;\n\n\t\tconst surface: Declaration = {\n\t\t\tkind: 'file-server',\n\t\t\tid: this.surfaceId,\n\t\t\tof: origin?.id ?? this.id,\n\t\t\t...(this.open.length ? { open: this.open } : {}),\n\t\t\tprovides: [this.keys.server],\n\t\t};\n\n\t\t// A vended bucket is declared here; a given one already declares itself,\n\t\t// and declaring it twice is the duplication the whole model removes.\n\t\tif (origin) return [surface];\n\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'objects',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.origin],\n\t\t\t\t...(this.options.versioned ? { versioned: true } : {}),\n\t\t\t},\n\t\t\tsurface,\n\t\t];\n\t}\n\n\t/**\n\t * The bucket's client, with the serving half added.\n\t *\n\t * Both addresses are read here, which is also how the environment reaches a\n\t * handler: the sniffer records what this reads, so `.dependsOn([uploads])`\n\t * carries the bucket URL and the server URL without either being written\n\t * down beside the handler.\n\t */\n\tprivate async connect(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<FileServerClient<TOpen>> {\n\t\tconst { origin, server } = options.envParser\n\t\t\t.create((get) => ({\n\t\t\t\torigin: get(this.keys.origin).string(),\n\t\t\t\tserver: get(this.keys.server).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\tconst storage = createStorageClient(origin);\n\t\tconst base = server.replace(/\\/+$/, '');\n\n\t\tconst serve = (key: string): string => {\n\t\t\tif (!this.serves(key)) throw new NotOpen(key, this.open);\n\n\t\t\treturn `${base}/${key.replace(/^\\/+/, '')}`;\n\t\t};\n\n\t\t// Delegating rather than copying: the bucket half is whatever the driver\n\t\t// produced, including anything it grows later, and only the serving half\n\t\t// is added on top.\n\t\treturn Object.assign(Object.create(storage) as StorageClient, {\n\t\t\turl: serve as (key: Served<TOpen>) => string,\n\t\t\topenUrl: serve,\n\t\t\tsignedUrl: (key: string, expiresIn?: number) =>\n\t\t\t\tstorage.getDownloadURL({ path: key } as never, expiresIn),\n\t\t}) as FileServerClient<TOpen>;\n\t}\n\n\t/**\n\t * Whether an open pattern admits a key.\n\t *\n\t * The runtime half of {@link Served}, and stricter than it: here a single\n\t * star stops at a segment boundary and a double star does not, which is the\n\t * distinction a template-literal type cannot draw and the infrastructure\n\t * does.\n\t */\n\tprivate serves(key: string): boolean {\n\t\treturn this.open.some((pattern) => globToRegExp(pattern).test(key));\n\t}\n}\n\n/**\n * One open pattern as an anchored expression.\n *\n * A double star crosses `/`; a single star does not. Both are consumed in one\n * left-to-right pass rather than by substitution, so a pattern cannot be\n * rewritten into a placeholder that a later pass mistakes for literal text.\n */\nfunction globToRegExp(pattern: string): RegExp {\n\tlet source = '';\n\n\tfor (let index = 0; index < pattern.length; index++) {\n\t\tconst character = pattern[index];\n\n\t\tif (character !== '*') {\n\t\t\tsource += character?.replace(/[.+^${}()|[\\]\\\\?]/, '\\\\$&') ?? '';\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (pattern[index + 1] === '*') {\n\t\t\tsource += '.*';\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tsource += '[^/]*';\n\t}\n\n\treturn new RegExp(`^${source}$`);\n}\n"],"mappings":"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"}

package/dist/file-server.d.cts

@@ -1,10 +1,8 @@
-import { Construct, Declarable } from "./construct-interface-D2nNkHUN.cjs";
+import { i as Declarable, n as Construct } from "./construct-interface-B1AfqRl4.cjs";
 import { Service } from "@geekmidas/services";
 import { ConstructName, Declaration } from "@geekmidas/manifest";
 import { StorageClient } from "@geekmidas/storage";
-
 //#region src/file-server.d.ts
-
 /**
  * A key an open pattern admits.
  *
@@ -23,9 +21,9 @@ import { StorageClient } from "@geekmidas/storage";
  * the cache behaviour, and by this construct's own runtime check. The type says
  * plausibly open; the infrastructure says definitely.
  */
-type Served<P extends string> = P extends `${infer Head}**` ? `${Head}${string}` : P extends `${infer Head}*${infer Tail}` ? `${Head}${string}${Tail}` : P;
+export type Served<P extends string> = P extends `${infer Head}**` ? `${Head}${string}` : P extends `${infer Head}*${infer Tail}` ? `${Head}${string}${Tail}` : P;
 /** What consuming a file server hands you: a bucket client that also serves. */
-interface FileServerClient<TOpen extends string = never> extends StorageClient {
+export interface FileServerClient<TOpen extends string = never> extends StorageClient {
   /**
    * The unsigned address of an open object.
    *
@@ -60,7 +58,7 @@ interface FileServerClient<TOpen extends string = never> extends StorageClient {
    */
   signedUrl(key: string, expiresIn?: number): Promise<string>;
 }
-interface FileServerOptions<TOpen extends string = never> {
+export interface FileServerOptions<TOpen extends string = never> {
   /**
    * Paths served without a signature. Everything else needs one.
    *
@@ -88,12 +86,12 @@ interface FileServerOptions<TOpen extends string = never> {
   origin?: Declarable;
 }
 /** A key was asked to be served unsigned, and no open pattern admits it. */
-declare class NotOpen extends Error {
+export declare class NotOpen extends Error {
   readonly key: string;
   readonly open: readonly string[];
   constructor(key: string, open: readonly string[]);
 }
-declare class FileServer<TName extends string = string, TOpen extends string = never> implements Construct<TName, FileServerClient<TOpen>> {
+export declare class FileServer<TName extends string = string, TOpen extends string = never> implements Construct<TName, FileServerClient<TOpen>> {
   private readonly options;
   readonly id: TName;
   readonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;
@@ -150,7 +148,5 @@ declare class FileServer<TName extends string = string, TOpen extends string = n
    */
   private serves;
 }
-//# sourceMappingURL=file-server.d.ts.map
 //#endregion
-export { FileServer, FileServerClient, FileServerOptions, NotOpen, Served };
 //# sourceMappingURL=file-server.d.cts.map

package/dist/file-server.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"file-server.d.cts","names":[],"sources":["../src/file-server.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;AAyJsB;;;;;;KA7FV,2BAA2B,iCACjC,kBACH,6CACI,gBAAgB,SACnB;;UAGa,uDACR;;;;;;;;;;WAUC,OAAO;;;;;;;;;;;;;;;;;;;;;;;8CAyB4B;;UAG5B;;;;;;;;;;;;;;kBAcA;;;;;;;;;;;WAWP;;;cAIG,OAAA,SAAgB,KAAK;;;;;cAerB,mFAGA,UAAU,OAAO,iBAAiB;;eAEjC;oBACK,QAAQ,aAAa,QAAQ,iBAAiB;;;;;;;;;kBAc3D,cAAc,kBACQ,kBAAkB;;;;;;;;;;;;;;;gBAuC/B;;;;;;;;;;aAoBH"}
+{"version":3,"file":"file-server.d.cts","names":[],"sources":["../src/file-server.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;YA4DY,OAAO,oBAAoB,mBAAmB,cACpD,kBACH,mBAAmB,cAAc,YAC7B,gBAAgB,SACnB;;iBAGa,iBAAiB,sCACzB;;;;;;;;;;EAUR,IAAI,KAAK,OAAO;;;;;;;;;;;EAYhB,QAAQ;;;;;;;;;;;;EAaR,UAAU,aAAa,qBAAqB;;iBAG5B,kBAAkB;;;;;;;;;;;;;;EAclC,gBAAgB;;EAEhB;;;;;;;;;EASA,SAAS;;;qBAIG,gBAAgB;WAElB;WACA;EAFV,YACU,aACA;;qBAYE,WACZ,+BACA,yCACY,UAAU,OAAO,iBAAiB;mBAkB5B;WAhBT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,iBAAiB;;WAGvD;mBAEQ;;;;;mBAMA;EAEjB,YACC,IAAI,cAAc,QACD,UAAS,kBAAkB;;;;;;;;;;;;;;;MAuCzC,UAAU;;;;;;;;;;EAoBd,WAAW;;;;;;;;;UAkCG;;;;;;;;;UAsCN"}

package/dist/file-server.d.mts

@@ -1,10 +1,8 @@
-import { Construct, Declarable } from "./construct-interface-BqwRNYA2.mjs";
+import { i as Declarable, n as Construct } from "./construct-interface-DluK3_da.mjs";
 import { ConstructName, Declaration } from "@geekmidas/manifest";
 import { StorageClient } from "@geekmidas/storage";
 import { Service } from "@geekmidas/services";
-
 //#region src/file-server.d.ts
-
 /**
  * A key an open pattern admits.
  *
@@ -23,9 +21,9 @@ import { Service } from "@geekmidas/services";
  * the cache behaviour, and by this construct's own runtime check. The type says
  * plausibly open; the infrastructure says definitely.
  */
-type Served<P extends string> = P extends `${infer Head}**` ? `${Head}${string}` : P extends `${infer Head}*${infer Tail}` ? `${Head}${string}${Tail}` : P;
+export type Served<P extends string> = P extends `${infer Head}**` ? `${Head}${string}` : P extends `${infer Head}*${infer Tail}` ? `${Head}${string}${Tail}` : P;
 /** What consuming a file server hands you: a bucket client that also serves. */
-interface FileServerClient<TOpen extends string = never> extends StorageClient {
+export interface FileServerClient<TOpen extends string = never> extends StorageClient {
   /**
    * The unsigned address of an open object.
    *
@@ -60,7 +58,7 @@ interface FileServerClient<TOpen extends string = never> extends StorageClient {
    */
   signedUrl(key: string, expiresIn?: number): Promise<string>;
 }
-interface FileServerOptions<TOpen extends string = never> {
+export interface FileServerOptions<TOpen extends string = never> {
   /**
    * Paths served without a signature. Everything else needs one.
    *
@@ -88,12 +86,12 @@ interface FileServerOptions<TOpen extends string = never> {
   origin?: Declarable;
 }
 /** A key was asked to be served unsigned, and no open pattern admits it. */
-declare class NotOpen extends Error {
+export declare class NotOpen extends Error {
   readonly key: string;
   readonly open: readonly string[];
   constructor(key: string, open: readonly string[]);
 }
-declare class FileServer<TName extends string = string, TOpen extends string = never> implements Construct<TName, FileServerClient<TOpen>> {
+export declare class FileServer<TName extends string = string, TOpen extends string = never> implements Construct<TName, FileServerClient<TOpen>> {
   private readonly options;
   readonly id: TName;
   readonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;
@@ -150,7 +148,5 @@ declare class FileServer<TName extends string = string, TOpen extends string = n
    */
   private serves;
 }
-//# sourceMappingURL=file-server.d.ts.map
 //#endregion
-export { FileServer, FileServerClient, FileServerOptions, NotOpen, Served };
 //# sourceMappingURL=file-server.d.mts.map

package/dist/file-server.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"file-server.d.mts","names":[],"sources":["../src/file-server.ts"],"sourcesContent":[],"mappings":";;;;;;;;;;;;;;;;;;;AAyJsB;;;;;;KA7FV,2BAA2B,iCACjC,kBACH,6CACI,gBAAgB,SACnB;;UAGa,uDACR;;;;;;;;;;WAUC,OAAO;;;;;;;;;;;;;;;;;;;;;;;8CAyB4B;;UAG5B;;;;;;;;;;;;;;kBAcA;;;;;;;;;;;WAWP;;;cAIG,OAAA,SAAgB,KAAK;;;;;cAerB,mFAGA,UAAU,OAAO,iBAAiB;;eAEjC;oBACK,QAAQ,aAAa,QAAQ,iBAAiB;;;;;;;;;kBAc3D,cAAc,kBACQ,kBAAkB;;;;;;;;;;;;;;;gBAuC/B;;;;;;;;;;aAoBH"}
+{"version":3,"file":"file-server.d.mts","names":[],"sources":["../src/file-server.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;YA4DY,OAAO,oBAAoB,mBAAmB,cACpD,kBACH,mBAAmB,cAAc,YAC7B,gBAAgB,SACnB;;iBAGa,iBAAiB,sCACzB;;;;;;;;;;EAUR,IAAI,KAAK,OAAO;;;;;;;;;;;EAYhB,QAAQ;;;;;;;;;;;;EAaR,UAAU,aAAa,qBAAqB;;iBAG5B,kBAAkB;;;;;;;;;;;;;;EAclC,gBAAgB;;EAEhB;;;;;;;;;EASA,SAAS;;;qBAIG,gBAAgB;WAElB;WACA;EAFV,YACU,aACA;;qBAYE,WACZ,+BACA,yCACY,UAAU,OAAO,iBAAiB;mBAkB5B;WAhBT,IAAI;WACJ,SAAS,QAAQ,aAAa,QAAQ,iBAAiB;;WAGvD;mBAEQ;;;;;mBAMA;EAEjB,YACC,IAAI,cAAc,QACD,UAAS,kBAAkB;;;;;;;;;;;;;;;MAuCzC,UAAU;;;;;;;;;;EAoBd,WAAW;;;;;;;;;UAkCG;;;;;;;;;UAsCN"}

package/dist/file-server.mjs

@@ -1,9 +1,40 @@
 import { canonicalId, provideKey, serviceKey } from "@geekmidas/manifest";
 import { createStorageClient } from "@geekmidas/storage";
-
 //#region src/file-server.ts
+/**
+* `FileServer` — a domain that serves a bucket's objects.
+*
+* `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never
+* public. Serving those objects on a domain is a different thing, and it is a
+* construct of its own rather than a flag on the bucket — see
+* `docs/design/constructs-paradigm.md`, "Why a separate construct, and what it
+* costs", for the comparison that rules the other two shapes out.
+*
+* ```ts
+* export const uploads = new FileServer('Uploads', { open: ['brand/**'] });
+*
+* uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket
+* uploads.url('brand/logo.png')                // open path — no signature
+* uploads.signedUrl('invoices/7.pdf')          // one object, one recipient
+* ```
+*
+* **One construct, one client, both halves.** How a file lands in the bucket is
+* the same whether or not it is served, so splitting the upload half from the
+* serving half would be ceremony rather than safety. The client is a *superset*
+* of `StorageClient`, made literal in the type, so anything taking
+* `services.uploads` keeps compiling when the construct behind it grows a
+* serving half.
+*
+* **The id names the bucket, not the surface.** This is the detail that has to
+* be right before anything ships, because getting it backwards is destructive:
+* the migration people actually perform is serving a bucket they already have,
+* and naming the bucket after the construct makes that edit *add* a node rather
+* than rename the one holding the data.
+*/
 /** A key was asked to be served unsigned, and no open pattern admits it. */
 var NotOpen = class extends Error {
+	key;
+	open;
 	constructor(key, open) {
 		super(`'${key}' is not served without a signature. ` + (open.length ? `Open paths: ${open.join(", ")}. Use signedUrl() for anything else.` : "This file server declares no open paths, so every object needs signedUrl()."));
 		this.key = key;
@@ -12,6 +43,7 @@ var NotOpen = class extends Error {
 	}
 };
 var FileServer = class {
+	options;
 	id;
 	service;
 	/** The id of the surface node, as opposed to the bucket's. */
@@ -146,7 +178,7 @@ function globToRegExp(pattern) {
 	}
 	return new RegExp(`^${source}$`);
 }
-
 //#endregion
 export { FileServer, NotOpen };
+
 //# sourceMappingURL=file-server.mjs.map

package/dist/file-server.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"file-server.mjs","names":["key: string","open: readonly string[]","id: ConstructName<TName>","options: FileServerOptions<TOpen>","surface: Declaration","options: ServiceRegisterOptions","expiresIn?: number","pattern: string"],"sources":["../src/file-server.ts"],"sourcesContent":["/**\n * `FileServer` — a domain that serves a bucket's objects.\n *\n * `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never\n * public. Serving those objects on a domain is a different thing, and it is a\n * construct of its own rather than a flag on the bucket — see\n * `docs/design/constructs-paradigm.md`, \"Why a separate construct, and what it\n * costs\", for the comparison that rules the other two shapes out.\n *\n * ```ts\n * export const uploads = new FileServer('Uploads', { open: ['brand/**'] });\n *\n * uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket\n * uploads.url('brand/logo.png')                // open path — no signature\n * uploads.signedUrl('invoices/7.pdf')          // one object, one recipient\n * ```\n *\n * **One construct, one client, both halves.** How a file lands in the bucket is\n * the same whether or not it is served, so splitting the upload half from the\n * serving half would be ceremony rather than safety. The client is a *superset*\n * of `StorageClient`, made literal in the type, so anything taking\n * `services.uploads` keeps compiling when the construct behind it grows a\n * serving half.\n *\n * **The id names the bucket, not the surface.** This is the detail that has to\n * be right before anything ships, because getting it backwards is destructive:\n * the migration people actually perform is serving a bucket they already have,\n * and naming the bucket after the construct makes that edit *add* a node rather\n * than rename the one holding the data.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport { createStorageClient, type StorageClient } from '@geekmidas/storage';\nimport type { Construct, Declarable } from './construct-interface';\n\n/**\n * A key an open pattern admits.\n *\n * The same template-literal trick `ConstructName` uses, so `open` is checked at\n * the call site rather than only at the edge:\n *\n * ```ts\n * files.url('brand/logo.png')       // ok\n * files.url(`avatars/${id}.png`)    // ok — a template literal still matches\n * files.url('invoices/7.pdf')       // not assignable — never served unsigned\n * ```\n *\n * A single star and a double star resolve to the same type, stated rather than\n * discovered: a template literal cannot exclude `/`, so this is a prefix-and-\n * suffix guard while the *exact* pattern is enforced by the bucket policy, by\n * the cache behaviour, and by this construct's own runtime check. The type says\n * plausibly open; the infrastructure says definitely.\n */\nexport type Served<P extends string> = P extends `${infer Head}**`\n\t? `${Head}${string}`\n\t: P extends `${infer Head}*${infer Tail}`\n\t\t? `${Head}${string}${Tail}`\n\t\t: P;\n\n/** What consuming a file server hands you: a bucket client that also serves. */\nexport interface FileServerClient<TOpen extends string = never>\n\textends StorageClient {\n\t/**\n\t * The unsigned address of an open object.\n\t *\n\t * Compile-checked against the declared patterns, *and* checked again at\n\t * runtime — a JavaScript caller gets no compiler, and minting an unsigned\n\t * URL for a private object is a leak rather than a mistake.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\turl(key: Served<TOpen>): string;\n\n\t/**\n\t * The same thing for a key the compiler cannot see.\n\t *\n\t * A fully dynamic key does not type, which is correct and is also the case\n\t * people will hit — so the escape hatch is a named method rather than a\n\t * cast, and it runs the *same* runtime check rather than being a way around\n\t * it.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\topenUrl(key: string): string;\n\n\t/**\n\t * A signed address for one object and one recipient.\n\t *\n\t * Today this is an **S3 presign at the bucket**, which is what works\n\t * unchanged against MinIO locally and against S3 deployed. It is deliberately\n\t * not described as a CDN URL: CloudFront signing is a different mechanism,\n\t * with different keys, against a different host, and it needs key material\n\t * this construct does not yet declare.\n\t *\n\t * @param expiresIn - minutes, matching `getUploadURL`.\n\t */\n\tsignedUrl(key: string, expiresIn?: number): Promise<string>;\n}\n\nexport interface FileServerOptions<TOpen extends string = never> {\n\t/**\n\t * Paths served without a signature. Everything else needs one.\n\t *\n\t * Private by default: a bucket where forgetting a flag publishes user\n\t * uploads is the wrong default, so this is an exception list, and listing it\n\t * in code means exactly one set of paths is unauthenticated and it is\n\t * reviewable in a diff.\n\t *\n\t * Uploading is deliberately *not* restricted to these. Writing to a path\n\t * that happens to be open is ordinary; the only asymmetry worth enforcing is\n\t * that you cannot hand out an unsigned URL for something the server would\n\t * refuse to serve unsigned.\n\t */\n\topen?: readonly TOpen[];\n\t/** Keep previous versions of an object. */\n\tversioned?: boolean;\n\t/**\n\t * A bucket declared elsewhere, instead of one of this server's own.\n\t *\n\t * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that\n\t * already exists, which is also how the two edges come back when you want\n\t * them separately — a handler depending on the bucket writes, a handler\n\t * depending on the server mints URLs.\n\t */\n\torigin?: Declarable;\n}\n\n/** A key was asked to be served unsigned, and no open pattern admits it. */\nexport class NotOpen extends Error {\n\tconstructor(\n\t\treadonly key: string,\n\t\treadonly open: readonly string[],\n\t) {\n\t\tsuper(\n\t\t\t`'${key}' is not served without a signature. ` +\n\t\t\t\t(open.length\n\t\t\t\t\t? `Open paths: ${open.join(', ')}. Use signedUrl() for anything else.`\n\t\t\t\t\t: 'This file server declares no open paths, so every object needs signedUrl().'),\n\t\t);\n\t\tthis.name = 'NotOpen';\n\t}\n}\n\nexport class FileServer<\n\tTName extends string = string,\n\tTOpen extends string = never,\n> implements Construct<TName, FileServerClient<TOpen>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;\n\n\t/** The id of the surface node, as opposed to the bucket's. */\n\treadonly surfaceId: string;\n\n\tprivate readonly open: readonly string[];\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the keys the\n\t * target publishes and the keys the client reads cannot drift.\n\t */\n\tprivate readonly keys: { origin: string; server: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: FileServerOptions<TOpen> = {},\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.open = options.open ?? [];\n\n\t\t// The surface takes the suffix and the bucket keeps the plain id, which\n\t\t// is what makes \"serve a bucket I already have\" an edit that adds a node\n\t\t// instead of renaming the one holding the data.\n\t\tconst originId = options.origin?.id ?? canonical;\n\t\tthis.surfaceId = `${canonical}Server`;\n\n\t\tthis.keys = {\n\t\t\torigin: provideKey(originId, 'url'),\n\t\t\tserver: provideKey(this.surfaceId, 'url'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\t/**\n\t * The served surface, as something an edge can point at.\n\t *\n\t * Depending on the `FileServer` itself points at the **bucket** — its\n\t * canonical node — which is right for a handler: it presigns and writes. But\n\t * a bucket's URL is never public, so a site depending on it gets nothing\n\t * inlined, which is correct and also useless.\n\t *\n\t * This is the other half: `.dependsOn([uploads.server])` points at the\n\t * surface, whose address *is* public, and is what puts\n\t * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape\n\t * `database.reader()` uses, and for the same reason — one construct owning\n\t * two addresses needs a way to name the second.\n\t */\n\tget server(): Declarable {\n\t\tconst surface = this.declare().find(\n\t\t\t(declaration) => declaration.id === this.surfaceId,\n\t\t);\n\n\t\treturn {\n\t\t\tid: this.surfaceId,\n\t\t\tdeclare: () => (surface ? [surface] : []),\n\t\t};\n\t}\n\n\t/**\n\t * The bucket and the surface over it — or just the surface, when the bucket\n\t * was declared elsewhere.\n\t *\n\t * The surface names its origin through `of`, which is what makes the\n\t * reference check work: an origin resolving to nothing is a build failure,\n\t * the same guarantee `assertDerivations` already gives a reader and a schema\n\t * tenant.\n\t */\n\tdeclare(): Declaration[] {\n\t\tconst origin = this.options.origin;\n\n\t\tconst surface: Declaration = {\n\t\t\tkind: 'file-server',\n\t\t\tid: this.surfaceId,\n\t\t\tof: origin?.id ?? this.id,\n\t\t\t...(this.open.length ? { open: this.open } : {}),\n\t\t\tprovides: [this.keys.server],\n\t\t};\n\n\t\t// A vended bucket is declared here; a given one already declares itself,\n\t\t// and declaring it twice is the duplication the whole model removes.\n\t\tif (origin) return [surface];\n\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'objects',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.origin],\n\t\t\t\t...(this.options.versioned ? { versioned: true } : {}),\n\t\t\t},\n\t\t\tsurface,\n\t\t];\n\t}\n\n\t/**\n\t * The bucket's client, with the serving half added.\n\t *\n\t * Both addresses are read here, which is also how the environment reaches a\n\t * handler: the sniffer records what this reads, so `.dependsOn([uploads])`\n\t * carries the bucket URL and the server URL without either being written\n\t * down beside the handler.\n\t */\n\tprivate async connect(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<FileServerClient<TOpen>> {\n\t\tconst { origin, server } = options.envParser\n\t\t\t.create((get) => ({\n\t\t\t\torigin: get(this.keys.origin).string(),\n\t\t\t\tserver: get(this.keys.server).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\tconst storage = createStorageClient(origin);\n\t\tconst base = server.replace(/\\/+$/, '');\n\n\t\tconst serve = (key: string): string => {\n\t\t\tif (!this.serves(key)) throw new NotOpen(key, this.open);\n\n\t\t\treturn `${base}/${key.replace(/^\\/+/, '')}`;\n\t\t};\n\n\t\t// Delegating rather than copying: the bucket half is whatever the driver\n\t\t// produced, including anything it grows later, and only the serving half\n\t\t// is added on top.\n\t\treturn Object.assign(Object.create(storage) as StorageClient, {\n\t\t\turl: serve as (key: Served<TOpen>) => string,\n\t\t\topenUrl: serve,\n\t\t\tsignedUrl: (key: string, expiresIn?: number) =>\n\t\t\t\tstorage.getDownloadURL({ path: key } as never, expiresIn),\n\t\t}) as FileServerClient<TOpen>;\n\t}\n\n\t/**\n\t * Whether an open pattern admits a key.\n\t *\n\t * The runtime half of {@link Served}, and stricter than it: here a single\n\t * star stops at a segment boundary and a double star does not, which is the\n\t * distinction a template-literal type cannot draw and the infrastructure\n\t * does.\n\t */\n\tprivate serves(key: string): boolean {\n\t\treturn this.open.some((pattern) => globToRegExp(pattern).test(key));\n\t}\n}\n\n/**\n * One open pattern as an anchored expression.\n *\n * A double star crosses `/`; a single star does not. Both are consumed in one\n * left-to-right pass rather than by substitution, so a pattern cannot be\n * rewritten into a placeholder that a later pass mistakes for literal text.\n */\nfunction globToRegExp(pattern: string): RegExp {\n\tlet source = '';\n\n\tfor (let index = 0; index < pattern.length; index++) {\n\t\tconst character = pattern[index];\n\n\t\tif (character !== '*') {\n\t\t\tsource += character?.replace(/[.+^${}()|[\\]\\\\?]/, '\\\\$&') ?? '';\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (pattern[index + 1] === '*') {\n\t\t\tsource += '.*';\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tsource += '[^/]*';\n\t}\n\n\treturn new RegExp(`^${source}$`);\n}\n"],"mappings":"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"}
+{"version":3,"file":"file-server.mjs","names":[],"sources":["../src/file-server.ts"],"sourcesContent":["/**\n * `FileServer` — a domain that serves a bucket's objects.\n *\n * `ObjectStorage` is the bucket: it writes, it presigns, and its URL is never\n * public. Serving those objects on a domain is a different thing, and it is a\n * construct of its own rather than a flag on the bucket — see\n * `docs/design/constructs-paradigm.md`, \"Why a separate construct, and what it\n * costs\", for the comparison that rules the other two shapes out.\n *\n * ```ts\n * export const uploads = new FileServer('Uploads', { open: ['brand/**'] });\n *\n * uploads.getUploadURL({ path, contentType })  // an S3 presign at the bucket\n * uploads.url('brand/logo.png')                // open path — no signature\n * uploads.signedUrl('invoices/7.pdf')          // one object, one recipient\n * ```\n *\n * **One construct, one client, both halves.** How a file lands in the bucket is\n * the same whether or not it is served, so splitting the upload half from the\n * serving half would be ceremony rather than safety. The client is a *superset*\n * of `StorageClient`, made literal in the type, so anything taking\n * `services.uploads` keeps compiling when the construct behind it grows a\n * serving half.\n *\n * **The id names the bucket, not the surface.** This is the detail that has to\n * be right before anything ships, because getting it backwards is destructive:\n * the migration people actually perform is serving a bucket they already have,\n * and naming the bucket after the construct makes that edit *add* a node rather\n * than rename the one holding the data.\n */\n\nimport {\n\ttype ConstructName,\n\tcanonicalId,\n\ttype Declaration,\n\tprovideKey,\n\tserviceKey,\n} from '@geekmidas/manifest';\nimport type { Service, ServiceRegisterOptions } from '@geekmidas/services';\nimport { createStorageClient, type StorageClient } from '@geekmidas/storage';\nimport type { Construct, Declarable } from './construct-interface';\n\n/**\n * A key an open pattern admits.\n *\n * The same template-literal trick `ConstructName` uses, so `open` is checked at\n * the call site rather than only at the edge:\n *\n * ```ts\n * files.url('brand/logo.png')       // ok\n * files.url(`avatars/${id}.png`)    // ok — a template literal still matches\n * files.url('invoices/7.pdf')       // not assignable — never served unsigned\n * ```\n *\n * A single star and a double star resolve to the same type, stated rather than\n * discovered: a template literal cannot exclude `/`, so this is a prefix-and-\n * suffix guard while the *exact* pattern is enforced by the bucket policy, by\n * the cache behaviour, and by this construct's own runtime check. The type says\n * plausibly open; the infrastructure says definitely.\n */\nexport type Served<P extends string> = P extends `${infer Head}**`\n\t? `${Head}${string}`\n\t: P extends `${infer Head}*${infer Tail}`\n\t\t? `${Head}${string}${Tail}`\n\t\t: P;\n\n/** What consuming a file server hands you: a bucket client that also serves. */\nexport interface FileServerClient<TOpen extends string = never>\n\textends StorageClient {\n\t/**\n\t * The unsigned address of an open object.\n\t *\n\t * Compile-checked against the declared patterns, *and* checked again at\n\t * runtime — a JavaScript caller gets no compiler, and minting an unsigned\n\t * URL for a private object is a leak rather than a mistake.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\turl(key: Served<TOpen>): string;\n\n\t/**\n\t * The same thing for a key the compiler cannot see.\n\t *\n\t * A fully dynamic key does not type, which is correct and is also the case\n\t * people will hit — so the escape hatch is a named method rather than a\n\t * cast, and it runs the *same* runtime check rather than being a way around\n\t * it.\n\t *\n\t * @throws {NotOpen} when the key matches no declared pattern.\n\t */\n\topenUrl(key: string): string;\n\n\t/**\n\t * A signed address for one object and one recipient.\n\t *\n\t * Today this is an **S3 presign at the bucket**, which is what works\n\t * unchanged against MinIO locally and against S3 deployed. It is deliberately\n\t * not described as a CDN URL: CloudFront signing is a different mechanism,\n\t * with different keys, against a different host, and it needs key material\n\t * this construct does not yet declare.\n\t *\n\t * @param expiresIn - minutes, matching `getUploadURL`.\n\t */\n\tsignedUrl(key: string, expiresIn?: number): Promise<string>;\n}\n\nexport interface FileServerOptions<TOpen extends string = never> {\n\t/**\n\t * Paths served without a signature. Everything else needs one.\n\t *\n\t * Private by default: a bucket where forgetting a flag publishes user\n\t * uploads is the wrong default, so this is an exception list, and listing it\n\t * in code means exactly one set of paths is unauthenticated and it is\n\t * reviewable in a diff.\n\t *\n\t * Uploading is deliberately *not* restricted to these. Writing to a path\n\t * that happens to be open is ordinary; the only asymmetry worth enforcing is\n\t * that you cannot hand out an unsigned URL for something the server would\n\t * refuse to serve unsigned.\n\t */\n\topen?: readonly TOpen[];\n\t/** Keep previous versions of an object. */\n\tversioned?: boolean;\n\t/**\n\t * A bucket declared elsewhere, instead of one of this server's own.\n\t *\n\t * `new FileServer('Uploads')` declares both nodes; this fronts a bucket that\n\t * already exists, which is also how the two edges come back when you want\n\t * them separately — a handler depending on the bucket writes, a handler\n\t * depending on the server mints URLs.\n\t */\n\torigin?: Declarable;\n}\n\n/** A key was asked to be served unsigned, and no open pattern admits it. */\nexport class NotOpen extends Error {\n\tconstructor(\n\t\treadonly key: string,\n\t\treadonly open: readonly string[],\n\t) {\n\t\tsuper(\n\t\t\t`'${key}' is not served without a signature. ` +\n\t\t\t\t(open.length\n\t\t\t\t\t? `Open paths: ${open.join(', ')}. Use signedUrl() for anything else.`\n\t\t\t\t\t: 'This file server declares no open paths, so every object needs signedUrl().'),\n\t\t);\n\t\tthis.name = 'NotOpen';\n\t}\n}\n\nexport class FileServer<\n\tTName extends string = string,\n\tTOpen extends string = never,\n> implements Construct<TName, FileServerClient<TOpen>>\n{\n\treadonly id: TName;\n\treadonly service: Service<Uncapitalize<TName>, FileServerClient<TOpen>>;\n\n\t/** The id of the surface node, as opposed to the bucket's. */\n\treadonly surfaceId: string;\n\n\tprivate readonly open: readonly string[];\n\n\t/**\n\t * Declared once and read by both `declare()` and `connect()`, so the keys the\n\t * target publishes and the keys the client reads cannot drift.\n\t */\n\tprivate readonly keys: { origin: string; server: string };\n\n\tconstructor(\n\t\tid: ConstructName<TName>,\n\t\tprivate readonly options: FileServerOptions<TOpen> = {},\n\t) {\n\t\tconst canonical = canonicalId(id as string);\n\n\t\tthis.id = canonical as TName;\n\t\tthis.open = options.open ?? [];\n\n\t\t// The surface takes the suffix and the bucket keeps the plain id, which\n\t\t// is what makes \"serve a bucket I already have\" an edit that adds a node\n\t\t// instead of renaming the one holding the data.\n\t\tconst originId = options.origin?.id ?? canonical;\n\t\tthis.surfaceId = `${canonical}Server`;\n\n\t\tthis.keys = {\n\t\t\torigin: provideKey(originId, 'url'),\n\t\t\tserver: provideKey(this.surfaceId, 'url'),\n\t\t};\n\n\t\t// A field, not a getter: consumers cache services by object identity.\n\t\tthis.service = {\n\t\t\tserviceName: serviceKey(canonical) as Uncapitalize<TName>,\n\t\t\tregister: (registerOptions) => this.connect(registerOptions),\n\t\t};\n\t}\n\n\t/**\n\t * The served surface, as something an edge can point at.\n\t *\n\t * Depending on the `FileServer` itself points at the **bucket** — its\n\t * canonical node — which is right for a handler: it presigns and writes. But\n\t * a bucket's URL is never public, so a site depending on it gets nothing\n\t * inlined, which is correct and also useless.\n\t *\n\t * This is the other half: `.dependsOn([uploads.server])` points at the\n\t * surface, whose address *is* public, and is what puts\n\t * `VITE_UPLOADS_SERVER_URL` in a bundle. The same accessor shape\n\t * `database.reader()` uses, and for the same reason — one construct owning\n\t * two addresses needs a way to name the second.\n\t */\n\tget server(): Declarable {\n\t\tconst surface = this.declare().find(\n\t\t\t(declaration) => declaration.id === this.surfaceId,\n\t\t);\n\n\t\treturn {\n\t\t\tid: this.surfaceId,\n\t\t\tdeclare: () => (surface ? [surface] : []),\n\t\t};\n\t}\n\n\t/**\n\t * The bucket and the surface over it — or just the surface, when the bucket\n\t * was declared elsewhere.\n\t *\n\t * The surface names its origin through `of`, which is what makes the\n\t * reference check work: an origin resolving to nothing is a build failure,\n\t * the same guarantee `assertDerivations` already gives a reader and a schema\n\t * tenant.\n\t */\n\tdeclare(): Declaration[] {\n\t\tconst origin = this.options.origin;\n\n\t\tconst surface: Declaration = {\n\t\t\tkind: 'file-server',\n\t\t\tid: this.surfaceId,\n\t\t\tof: origin?.id ?? this.id,\n\t\t\t...(this.open.length ? { open: this.open } : {}),\n\t\t\tprovides: [this.keys.server],\n\t\t};\n\n\t\t// A vended bucket is declared here; a given one already declares itself,\n\t\t// and declaring it twice is the duplication the whole model removes.\n\t\tif (origin) return [surface];\n\n\t\treturn [\n\t\t\t{\n\t\t\t\tkind: 'objects',\n\t\t\t\tid: this.id,\n\t\t\t\tprovides: [this.keys.origin],\n\t\t\t\t...(this.options.versioned ? { versioned: true } : {}),\n\t\t\t},\n\t\t\tsurface,\n\t\t];\n\t}\n\n\t/**\n\t * The bucket's client, with the serving half added.\n\t *\n\t * Both addresses are read here, which is also how the environment reaches a\n\t * handler: the sniffer records what this reads, so `.dependsOn([uploads])`\n\t * carries the bucket URL and the server URL without either being written\n\t * down beside the handler.\n\t */\n\tprivate async connect(\n\t\toptions: ServiceRegisterOptions,\n\t): Promise<FileServerClient<TOpen>> {\n\t\tconst { origin, server } = options.envParser\n\t\t\t.create((get) => ({\n\t\t\t\torigin: get(this.keys.origin).string(),\n\t\t\t\tserver: get(this.keys.server).string(),\n\t\t\t}))\n\t\t\t.parse();\n\n\t\tconst storage = createStorageClient(origin);\n\t\tconst base = server.replace(/\\/+$/, '');\n\n\t\tconst serve = (key: string): string => {\n\t\t\tif (!this.serves(key)) throw new NotOpen(key, this.open);\n\n\t\t\treturn `${base}/${key.replace(/^\\/+/, '')}`;\n\t\t};\n\n\t\t// Delegating rather than copying: the bucket half is whatever the driver\n\t\t// produced, including anything it grows later, and only the serving half\n\t\t// is added on top.\n\t\treturn Object.assign(Object.create(storage) as StorageClient, {\n\t\t\turl: serve as (key: Served<TOpen>) => string,\n\t\t\topenUrl: serve,\n\t\t\tsignedUrl: (key: string, expiresIn?: number) =>\n\t\t\t\tstorage.getDownloadURL({ path: key } as never, expiresIn),\n\t\t}) as FileServerClient<TOpen>;\n\t}\n\n\t/**\n\t * Whether an open pattern admits a key.\n\t *\n\t * The runtime half of {@link Served}, and stricter than it: here a single\n\t * star stops at a segment boundary and a double star does not, which is the\n\t * distinction a template-literal type cannot draw and the infrastructure\n\t * does.\n\t */\n\tprivate serves(key: string): boolean {\n\t\treturn this.open.some((pattern) => globToRegExp(pattern).test(key));\n\t}\n}\n\n/**\n * One open pattern as an anchored expression.\n *\n * A double star crosses `/`; a single star does not. Both are consumed in one\n * left-to-right pass rather than by substitution, so a pattern cannot be\n * rewritten into a placeholder that a later pass mistakes for literal text.\n */\nfunction globToRegExp(pattern: string): RegExp {\n\tlet source = '';\n\n\tfor (let index = 0; index < pattern.length; index++) {\n\t\tconst character = pattern[index];\n\n\t\tif (character !== '*') {\n\t\t\tsource += character?.replace(/[.+^${}()|[\\]\\\\?]/, '\\\\$&') ?? '';\n\t\t\tcontinue;\n\t\t}\n\n\t\tif (pattern[index + 1] === '*') {\n\t\t\tsource += '.*';\n\t\t\tindex++;\n\t\t\tcontinue;\n\t\t}\n\n\t\tsource += '[^/]*';\n\t}\n\n\treturn new RegExp(`^${source}$`);\n}\n"],"mappings":"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"}