@monoflake/sdk 0.0.0

package/dist/src/index.d.ts

@@ -0,0 +1,218 @@
+import { GITHUB_OWNER, LOOPBACK_HOST, Normalized, PORT_OFFSET, isDevHost, loopbackUrl, normalizePath, normalizedLocation } from "@canmi/me/urls";
+//#region src/index.d.ts
+/**
+ * The repositories whose deploy runs the hook passes to the nodes, as GitHub names them: the two
+ * whose apps a node runs. Each node holds its own list too, in `DEPLOY_SOURCES`, and that one
+ * decides. See infra's spec/architecture/host.md, "The machine pulls; nothing pushes into it".
+ */
+export declare const DEPLOY_SOURCES: readonly string[];
+/**
+ * The ports each app answers on in development.
+ *
+ * Pinned, and bound by exactly one checkout at a time. The gaps are the inspector ports, which
+ * wrangler takes as port + 1, and they keep clear of LOCAL_PORT (mise.toml). A second copy of an
+ * app collides here rather than drifting to a free port, which is the cheapest mutex there is.
+ * See spec/toolchain.md.
+ */
+export declare const PINNED_PORTS: {
+  readonly site: 26511;
+  readonly api: 26512;
+  readonly alias: 26514;
+  readonly cdn: 26516;
+  readonly panel: 26519;
+};
+/** Workers reached by binding alone: a port that is the mutex, and no address. */
+export declare const BOUND_PORTS: {
+  readonly quota: 26523;
+};
+/** The ports this checkout's servers bind: the pinned ones, shifted in the sandbox. */
+export declare const DEVELOPMENT_PORTS: { readonly [App in keyof typeof PINNED_PORTS | keyof typeof BOUND_PORTS]: number; };
+export type AppName = keyof typeof PINNED_PORTS;
+export type DevelopmentUrls = Readonly<Record<AppName | 'symlink', string>>;
+/**
+ * Where the alias layer and the CDN are reached *from a page* in development: through the site.
+ *
+ * A page carries no host of its own for either prefix -- see spec/toolchain.md, "They bind
+ * every interface, and the other two are reached through the site", for why that is what
+ * makes the site work from a phone on the same network. The site's API needs no proxy: the
+ * site's Worker answers it under `/api/` itself.
+ */
+export declare const DEVELOPMENT_PROXY_PATHS: {
+  readonly alias: '/alias';
+  readonly symlink: '/symlink';
+  readonly cdn: '/cdn';
+};
+export declare function developmentUrl(app: AppName): string;
+/**
+ * Every app's address in development. The service layer is reached through the development gateway,
+ * as it is in production, so its CORS and its lifetimes hold here too; the gateway has no short
+ * hosts here, so each is a service of the API host, at the version its short host pins. See
+ * spec/architecture/gateway.md and spec/architecture/services.md, "Development goes through the
+ * gateway too".
+ */
+export declare function developmentUrls(): DevelopmentUrls;
+export declare const URLS: {
+  readonly apps: {
+    readonly development: Readonly<Record<"alias" | "api" | "cdn" | "panel" | "site" | "symlink", string>>;
+    readonly production: {
+      readonly site: "https://canmi.net";
+      readonly api: "https://api.monoflake.com/v1/site";
+      readonly alias: "https://ill.li";
+      readonly symlink: 'https://symlink.si';
+      readonly cdn: 'https://cdn.monoflake.com';
+      readonly panel: "https://infra.internal.ixc.one";
+    };
+  };
+  readonly source: "https://github.com/canmi21/web";
+  readonly internal: {
+    readonly panel: 'https://infra.internal.ixc.one';
+    readonly keeper: 'https://keeper.internal.ixc.one';
+    readonly host: 'http://host:11011';
+    readonly app: 'https://canmi.app';
+    readonly infra: 'https://ffoni.com';
+    readonly alias: 'https://ill.li';
+    readonly ledger: "https://api.internal.ixc.one/ledger";
+    readonly cron: "https://api.internal.ixc.one/cron";
+    readonly shot: "https://api.monoflake.com/v1/shot";
+    readonly api: {
+      readonly private: 'https://api.internal.ixc.one';
+      readonly public: 'https://api.monoflake.com';
+    };
+    readonly status: {
+      readonly canonical: 'https://status.canmi.app';
+      readonly mirror: 'https://canmi.vercel.app';
+    };
+  };
+  readonly contact: {
+    readonly security: 'mailto:security@canmi.net';
+  };
+  readonly external: {
+    readonly github: {
+      readonly web: 'https://github.com';
+      readonly api: 'https://api.github.com';
+      readonly raw: 'https://raw.githubusercontent.com';
+      readonly avatars: 'https://avatars.githubusercontent.com';
+      readonly cdn: 'https://cdn.jsdelivr.net/gh';
+    };
+    readonly google: {
+      readonly sourcePreferences: 'https://www.google.com/preferences/source';
+    };
+    readonly registries: {
+      readonly npm: 'https://www.npmjs.com';
+      readonly cargo: 'https://crates.io';
+      readonly cargoIndex: 'https://index.crates.io';
+    };
+    readonly spdx: 'https://spdx.org/licenses';
+    readonly robotstxt: 'https://www.robotstxt.org/robotstxt.html';
+    readonly contentSignals: 'https://contentsignals.org';
+    readonly contentUsage: 'https://datatracker.ietf.org/doc/draft-ietf-aipref-attach/';
+    readonly agentIncident: 'https://openai.com/index/hugging-face-incident-and-the-road-ahead/';
+    readonly sentry: {
+      readonly site: 'https://a7f2f790ed2fa4f8e0c4310d26d9c39f@o4511131162116096.ingest.us.sentry.io/4511380121976832';
+      readonly status: string | undefined;
+    };
+    readonly feedsmith: 'https://feedsmith.dev';
+    readonly indexnow: 'https://api.indexnow.org/IndexNow';
+    readonly social: {
+      readonly telegram: 'https://t.me';
+      readonly twitter: 'https://twitter.com';
+      readonly twitterIntent: 'https://twitter.com/intent/follow';
+      readonly fediverse: 'https://nya.one';
+      readonly bluesky: 'https://bsky.app/profile';
+    };
+    readonly rust: {
+      readonly docs: 'https://docs.rs';
+      readonly lib: 'https://lib.rs';
+    };
+    readonly webring: {
+      readonly travellings: 'https://www.travellings.cn/go.html';
+      readonly moe: 'https://travel.moe/go?travel=on';
+    };
+    readonly icpmoe: 'https://icp.gov.moe';
+    readonly umami: 'https://cloud.umami.is/script.js';
+    readonly umamiGateway: 'https://gateway.umami.is';
+    readonly openpanel: 'https://api.openpanel.dev';
+    readonly googleFonts: {
+      readonly css: 'https://fonts.googleapis.com';
+      readonly static: 'https://fonts.gstatic.com';
+    };
+    readonly doh: {
+      readonly cloudflare: 'https://1.1.1.1/dns-query';
+      readonly google: 'https://8.8.8.8/resolve';
+    };
+    readonly geolite: {
+      readonly city: 'https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-City.mmdb';
+      readonly asn: 'https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-ASN.mmdb';
+      readonly maxmind: 'https://www.maxmind.com';
+    };
+  };
+};
+/**
+ * The service layer's hostnames, every one bound to the gateway, and the codes a deployment's own
+ * hostname is spelled from: `{service}-{region}-{provider}` under `deployments`. A provider or a
+ * region is added here before anything is placed on it. See spec/architecture/gateway.md.
+ */
+export declare const GATEWAY: {
+  readonly domains: readonly ['monoflake.com', 'monoflake.net'];
+  readonly api: 'api.monoflake.com';
+  readonly cdn: 'cdn.monoflake.com';
+  readonly deployments: 'ixc.one';
+  readonly alias: 'ill.li';
+  readonly symlink: 'symlink.si';
+  readonly retired: {
+    readonly api: 'api.ffoni.com';
+    readonly cdn: 'cdn.ffoni.com';
+  };
+  readonly providers: {
+    readonly int: 'our own machines';
+    readonly cf: 'Cloudflare';
+    readonly vcl: 'Vercel';
+  };
+  readonly regions: {
+    readonly rdu: 'the machine at home, by Raleigh-Durham';
+    readonly glo: 'everywhere, as a Worker runs';
+  };
+};
+/**
+ * Every hostname the gateway answers at home, as a certificate and a router name them: a wildcard
+ * over each zone it owns below the apex, and the two apexes it is. The retired hosts are left out:
+ * the house never asks them. See infra's spec/architecture/host.md, "The inside side answers the
+ * internal gateway alone".
+ */
+export declare const GATEWAY_HOSTS: readonly string[];
+/**
+ * The names the gateway answers at home, exactly, as the house's resolver answers them: the API and
+ * CDN hosts of each domain and the two apexes, and a deployment's own name, read as the profiles
+ * read it, from the registered regions and providers. Nothing else in those zones is the gateway's,
+ * so nothing else is answered with the node. See infra's spec/architecture/host.md, "The resolver
+ * answers the gateway's names, and passes the rest on".
+ */
+export declare const GATEWAY_NAMES: {
+  readonly exact: readonly [...string[], "ill.li", "symlink.si"];
+  readonly deployments: {
+    readonly zone: "ixc.one";
+    readonly regions: string[];
+    readonly providers: string[];
+  };
+};
+/**
+ * Where each consumer's pages are served, by its service code: what a declaration's `cors.origins`
+ * names, so no `service.toml` spells an origin. The status page has three doors, the platform's
+ * own among them. See spec/architecture/gateway.md, "A route names who may call it by service
+ * code".
+ */
+export declare const PAGE_ORIGINS: Readonly<Record<string, readonly string[]>>;
+export type UrlEnvironment = keyof typeof URLS.apps;
+export type UrlMap = (typeof URLS.apps)[UrlEnvironment];
+export declare function pickUrls(isDev: boolean): UrlMap;
+/**
+ * The same map as `pickUrls`, as a page served by the site should ask for it.
+ *
+ * Two functions because two consumers want opposite things from the development entry: a
+ * worker wants origins it can put in a CORS list or a redirect, while a page wants paths, since
+ * the host it should ask is whichever one it was opened from and need not be `localhost`.
+ * Identical to `pickUrls` in production, where nothing is proxied.
+ */
+export declare function pageUrls(isDev: boolean): UrlMap;
+//#endregion
+export { GITHUB_OWNER, LOOPBACK_HOST, type Normalized, PORT_OFFSET, isDevHost, loopbackUrl, normalizePath, normalizedLocation };

package/dist/src/index.js

@@ -0,0 +1,219 @@
+import { CONTACT, EXTERNAL, GITHUB_OWNER, LOOPBACK_HOST, PORT_OFFSET, SITE, SITE_PORT, SOURCE, isDevHost, loopbackUrl, normalizePath, normalizedLocation } from "@canmi/me/urls";
+import { INFRA, PANEL_PORT } from "@monoflake/urls";
+//#region src/index.ts
+/**
+* The platform's addresses, and the whole map as everything above infra reads it: the platform's
+* own declared here, the author's from `canmi` and infra's from `@monoflake/urls`, composed into
+* one shape so a caller asks one place and the Rust mirror has one source. See
+* spec/architecture/layers.md, "Addresses are split by who owns the name".
+*/
+/**
+* The repositories whose deploy runs the hook passes to the nodes, as GitHub names them: the two
+* whose apps a node runs. Each node holds its own list too, in `DEPLOY_SOURCES`, and that one
+* decides. See infra's spec/architecture/host.md, "The machine pulls; nothing pushes into it".
+*/
+const DEPLOY_SOURCES = ["monoflake/infra", "monoflake/platform"];
+/**
+* The ports each app answers on in development.
+*
+* Pinned, and bound by exactly one checkout at a time. The gaps are the inspector ports, which
+* wrangler takes as port + 1, and they keep clear of LOCAL_PORT (mise.toml). A second copy of an
+* app collides here rather than drifting to a free port, which is the cheapest mutex there is.
+* See spec/toolchain.md.
+*/
+const PINNED_PORTS = {
+	site: SITE_PORT,
+	api: 26512,
+	alias: 26514,
+	cdn: 26516,
+	panel: PANEL_PORT
+};
+/** Workers reached by binding alone: a port that is the mutex, and no address. */
+const BOUND_PORTS = { quota: 26523 };
+/** The ports this checkout's servers bind: the pinned ones, shifted in the sandbox. */
+const DEVELOPMENT_PORTS = Object.fromEntries(Object.entries({
+	...PINNED_PORTS,
+	...BOUND_PORTS
+}).map(([app, port]) => [app, port + PORT_OFFSET]));
+/** The site's scope of the API host, which is the service's name, `site`. */
+const SITE_SCOPE = "site";
+/**
+* Where the alias layer and the CDN are reached *from a page* in development: through the site.
+*
+* A page carries no host of its own for either prefix -- see spec/toolchain.md, "They bind
+* every interface, and the other two are reached through the site", for why that is what
+* makes the site work from a phone on the same network. The site's API needs no proxy: the
+* site's Worker answers it under `/api/` itself.
+*/
+const DEVELOPMENT_PROXY_PATHS = {
+	alias: "/alias",
+	symlink: "/symlink",
+	cdn: "/cdn"
+};
+function developmentUrl(app) {
+	return `http://localhost:${DEVELOPMENT_PORTS[app]}`;
+}
+/**
+* Every app's address in development. The service layer is reached through the development gateway,
+* as it is in production, so its CORS and its lifetimes hold here too; the gateway has no short
+* hosts here, so each is a service of the API host, at the version its short host pins. See
+* spec/architecture/gateway.md and spec/architecture/services.md, "Development goes through the
+* gateway too".
+*/
+function developmentUrls() {
+	const gateway = developmentUrl("api");
+	return {
+		site: developmentUrl("site"),
+		api: `${gateway}/v1/${SITE_SCOPE}`,
+		alias: `${gateway}/v1/aka`,
+		symlink: `${gateway}/v1/aka/symlink`,
+		cdn: `${gateway}/v3/cdn`,
+		panel: developmentUrl("panel")
+	};
+}
+const development = developmentUrls();
+/** The API host's two sides: private, where every container asks, and public, past the gateway. */
+const API = {
+	private: "https://api.internal.ixc.one",
+	public: "https://api.monoflake.com"
+};
+/**
+* The domains owned here, which the production map below reads rather than spelling twice. `infra`
+* is the retired apex api and cdn hung off; `alias` the alias layer's. `app` is the suffix every
+* interface is on behind Access, see spec/architecture/services.md; `panel`, `keeper` and `host`
+* are infra's, see infra's spec/architecture/host.md; `ledger` is where every service records its
+* tasks, see ledger.md; `shot` is the public scope a capture's pictures are named under, see
+* shot.md.
+*/
+const INTERNAL = {
+	app: "https://canmi.app",
+	infra: "https://ffoni.com",
+	alias: "https://ill.li",
+	...INFRA,
+	ledger: `${API.private}/ledger`,
+	cron: `${API.private}/cron`,
+	shot: `${API.public}/v1/shot`,
+	api: API,
+	status: {
+		canonical: "https://status.canmi.app",
+		mirror: "https://canmi.vercel.app"
+	}
+};
+const URLS = {
+	apps: {
+		development,
+		production: {
+			site: SITE,
+			api: `${API.public}/v1/${SITE_SCOPE}`,
+			alias: INTERNAL.alias,
+			symlink: "https://symlink.si",
+			cdn: "https://cdn.monoflake.com",
+			panel: INTERNAL.panel
+		}
+	},
+	source: SOURCE,
+	internal: INTERNAL,
+	contact: CONTACT,
+	external: {
+		...EXTERNAL,
+		doh: {
+			cloudflare: "https://1.1.1.1/dns-query",
+			google: "https://8.8.8.8/resolve"
+		},
+		geolite: {
+			city: "https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-City.mmdb",
+			asn: "https://github.com/P3TERX/GeoLite.mmdb/releases/latest/download/GeoLite2-ASN.mmdb",
+			maxmind: "https://www.maxmind.com"
+		}
+	}
+};
+/**
+* The service layer's hostnames, every one bound to the gateway, and the codes a deployment's own
+* hostname is spelled from: `{service}-{region}-{provider}` under `deployments`. A provider or a
+* region is added here before anything is placed on it. See spec/architecture/gateway.md.
+*/
+const GATEWAY = {
+	domains: ["monoflake.com", "monoflake.net"],
+	api: "api.monoflake.com",
+	cdn: "cdn.monoflake.com",
+	deployments: "ixc.one",
+	alias: "ill.li",
+	symlink: "symlink.si",
+	retired: {
+		api: "api.ffoni.com",
+		cdn: "cdn.ffoni.com"
+	},
+	providers: {
+		int: "our own machines",
+		cf: "Cloudflare",
+		vcl: "Vercel"
+	},
+	regions: {
+		rdu: "the machine at home, by Raleigh-Durham",
+		glo: "everywhere, as a Worker runs"
+	}
+};
+/**
+* Every hostname the gateway answers at home, as a certificate and a router name them: a wildcard
+* over each zone it owns below the apex, and the two apexes it is. The retired hosts are left out:
+* the house never asks them. See infra's spec/architecture/host.md, "The inside side answers the
+* internal gateway alone".
+*/
+const GATEWAY_HOSTS = [
+	...GATEWAY.domains.map((domain) => `*.${domain}`),
+	`*.${GATEWAY.deployments}`,
+	GATEWAY.alias,
+	GATEWAY.symlink
+];
+/**
+* The names the gateway answers at home, exactly, as the house's resolver answers them: the API and
+* CDN hosts of each domain and the two apexes, and a deployment's own name, read as the profiles
+* read it, from the registered regions and providers. Nothing else in those zones is the gateway's,
+* so nothing else is answered with the node. See infra's spec/architecture/host.md, "The resolver
+* answers the gateway's names, and passes the rest on".
+*/
+const GATEWAY_NAMES = {
+	exact: [
+		...GATEWAY.domains.flatMap((domain) => [`api.${domain}`, `cdn.${domain}`]),
+		GATEWAY.alias,
+		GATEWAY.symlink
+	],
+	deployments: {
+		zone: GATEWAY.deployments,
+		regions: Object.keys(GATEWAY.regions),
+		providers: Object.keys(GATEWAY.providers)
+	}
+};
+/**
+* Where each consumer's pages are served, by its service code: what a declaration's `cors.origins`
+* names, so no `service.toml` spells an origin. The status page has three doors, the platform's
+* own among them. See spec/architecture/gateway.md, "A route names who may call it by service
+* code".
+*/
+const PAGE_ORIGINS = {
+	site: [URLS.apps.production.site],
+	status: [
+		INTERNAL.status.canonical,
+		INTERNAL.status.mirror,
+		INTERNAL.app
+	]
+};
+function pickUrls(isDev) {
+	return isDev ? URLS.apps.development : URLS.apps.production;
+}
+/**
+* The same map as `pickUrls`, as a page served by the site should ask for it.
+*
+* Two functions because two consumers want opposite things from the development entry: a
+* worker wants origins it can put in a CORS list or a redirect, while a page wants paths, since
+* the host it should ask is whichever one it was opened from and need not be `localhost`.
+* Identical to `pickUrls` in production, where nothing is proxied.
+*/
+function pageUrls(isDev) {
+	return isDev ? {
+		...URLS.apps.development,
+		...DEVELOPMENT_PROXY_PATHS
+	} : URLS.apps.production;
+}
+//#endregion
+export { BOUND_PORTS, DEPLOY_SOURCES, DEVELOPMENT_PORTS, DEVELOPMENT_PROXY_PATHS, GATEWAY, GATEWAY_HOSTS, GATEWAY_NAMES, GITHUB_OWNER, LOOPBACK_HOST, PAGE_ORIGINS, PINNED_PORTS, PORT_OFFSET, URLS, developmentUrl, developmentUrls, isDevHost, loopbackUrl, normalizePath, normalizedLocation, pageUrls, pickUrls };

package/dist/store/src/index.d.ts

@@ -0,0 +1,92 @@
+import { recordKey, storageKey } from "../../artifacts/src/index.js";
+import { Fetcher, R2Bucket } from "@cloudflare/workers-types";
+//#region store/src/index.d.ts
+export type Bindings = {
+  STORE?: R2Bucket;
+  /** Present only under `wrangler dev --assets`; see the dev task in mise.toml. */
+  ASSETS?: Fetcher;
+};
+export type Found = {
+  body: ReadableStream;
+  contentType: string;
+  etag?: string;
+  /** What was served, when a range was asked for and satisfied. Absent for a whole object. */
+  partial?: {
+    offset: number;
+    length: number;
+    total: number;
+  };
+};
+/**
+ * A range that names nothing inside the object.
+ *
+ * Its own result rather than a null, because the two mean opposite things to a caller: a missing
+ * object is 404 and a range past the end of a present one is 416, and 416 has to report the size
+ * so the client can ask again. Answering 404 for the second would send a browser looking for a
+ * file it already found.
+ */
+export type Unsatisfiable = {
+  unsatisfiable: true;
+  total: number;
+};
+export declare function isUnsatisfiable(value: Found | Unsatisfiable | null): value is Unsatisfiable;
+/**
+ * Read an object, or the part of one a `Range` header asks for.
+ *
+ * `range` is the header verbatim, parsed here in the one place with a grammar to obey -- see
+ * web's spec/architecture/data.md, "Assets are addressed by their content", for why the worker
+ * resolves it rather than the bucket, and what an unparseable or multipart request gets instead.
+ */
+export declare function read(env: Bindings, key: string): Promise<Found | null>;
+export declare function read(env: Bindings, key: string, range: string | null | undefined): Promise<Found | Unsatisfiable | null>;
+/** What a head reports. `uploaded` is null only where the store keeps no date; see `measure`. */
+export type Measured = {
+  size: number;
+  uploaded: Date | null;
+};
+/**
+ * What is known about an object under a key, without reading a byte of it.
+ *
+ * A caller that has to refuse work before paying for it needs the size first: an isolate gets
+ * 128 MB for its heap and its WebAssembly together, so a length that arrives alongside the bytes
+ * arrives too late to be a limit. Null is no such object, which makes this a presence check too.
+ * The date rides along because the same head already carries it, and a caller wanting both
+ * should not spend a second round trip on the second one.
+ */
+export declare function measure(env: Bindings, key: string): Promise<Measured | null>;
+export declare function isContentId(value: string): boolean;
+/**
+ * A stored object as an HTTP response, with ETag only when the store supplied one.
+ *
+ * `Accept-Ranges` on every one of them, because every object here is served through a route that
+ * can answer a range -- a player seeking, a `<video>` element probing for duration, a resumed
+ * download. The header is what tells a client it may ask; without it a browser fetches whole
+ * files to read a byte near the end of them.
+ */
+export declare function toResponse(found: Found): Response;
+/**
+ * The answer to a range that names nothing inside the object.
+ *
+ * 416 carries the size so the client can ask again knowing it, which is the whole reason this is
+ * not a 404: the object is there, the question was wrong.
+ */
+export declare function unsatisfiableResponse(total: number): Response;
+/**
+ * Bytes already in hand, answered as a `Range` asked for them.
+ *
+ * For a body that was derived rather than stored: there is no object to ask the bucket for a part
+ * of, so the artifact is produced whole and the slice is taken here. The grammar stays in this
+ * module -- one parser, one set of spellings -- and a header it does not implement is served
+ * whole, which is what a recipient is allowed to do. See spec/architecture/delivery.md.
+ */
+export declare function rangedResponse(bytes: Uint8Array, contentType: string, range: string | null | undefined): Response;
+/**
+ * Content type from the key, for objects stored without one.
+ *
+ * R2 keeps whatever `httpMetadata` was set at upload, and rclone does set it, but an object
+ * put by hand through the dashboard has none. Serving those as `application/octet-stream`
+ * makes a browser download a favicon instead of drawing it.
+ */
+export declare function contentTypeFor(key: string): string;
+//#endregion
+export { recordKey, storageKey };