everything-dev/dist/services/resolution/resolver.d.mts

A consolidated product package for building Module Federation apps with oRPC APIs.

import { Cause, Context, Effect, Layer, Schema } from "effect";
//#region src/services/resolution/resolver.d.ts
/**
 * Bundle resolution — the one seam every boot-time byte crosses (config
 * manifest discovery, contract-type fetches, federation remote loading, SSR
 * serving). Two tiers, one policy (ADR 0011/0021):
 *
 * - Self-contained runtime image: a staged namespace under `BOS_BUNDLE_DIR`
 *   resolves from disk; a miss falls through to the network so a partially-
 *   staged namespace boots over the wire instead of failing.
 * - Registry tier: plain resilient network fetch — CDN is the single
 *   distribution source. The stale-if-error disk cache exists only behind an
 *   explicit `BOS_BUNDLE_CACHE_DIR` opt-in; cached bytes are a resilience
 *   artifact, never a deployment, so a post-reset boot can never satisfy
 *   itself with pre-reset bytes.
 */
interface BundleNamespace {
  readonly bundleDir: string;
  readonly account: string;
  readonly gateway: string;
}
declare const BundleReadError_base: Schema.Class<BundleReadError, Schema.TaggedStruct<"BundleReadError", {
  readonly path: Schema.String;
  readonly cause: Schema.optional<Schema.Unknown>;
}>, Cause.YieldableError>;
declare class BundleReadError extends BundleReadError_base {}
/**
 * Maps a bundle URL onto the staged namespace layout. Bundle URLs carry their
 * namespace in the path (`…/bundles/<account>/<gateway>/<workspace>/…`); the
 * staged layout mirrors it under `<bundleDir>/<account>/<gateway>/…`. The
 * namespace is taken from the URL itself — this answers "which staged
 * directory do these bytes live in?" rather than "is this my namespace?" —
 * and the result is contained within the account/gateway directory. Returns
 * null for foreign shapes.
 */
declare function bundleUrlToStagedPath(url: string, bundleDir: string): string | null;
/** Resolve a relative config-supplied path inside `dir`, or null on escape. */
declare function resolveContained(dir: string, relative: string): string | null;
/**
 * Own-namespace path for a bundle URL: the shared URL→staged-path mapping,
 * narrowed to the runtime identity — a URL whose encoded namespace differs
 * from `namespace.account`/`namespace.gateway` must fall to the network,
 * never serve a sibling namespace's staged bytes.
 */
declare function bundleUrlToLocalPath(url: string, namespace: BundleNamespace): string | null;
declare const BundleResolver_base: Context.ServiceClass<BundleResolver, "everything-dev/resolver/BundleResolver", {
  /** Resolve a fetch target from the staged namespace; null = miss or not our namespace — fall through to the network. */
  readonly lookup: (input: string | URL | Request) => Effect.Effect<Response | null>;
}>;
declare class BundleResolver extends BundleResolver_base {
  static layer(namespace: BundleNamespace | undefined): Layer.Layer<BundleResolver>;
}
interface BundleFetchHandle {
  readonly uninstall: () => Promise<void>;
}
interface BundleFetchOptions {
  /** Own-namespace FS resolution — requires a staged `BOS_BUNDLE_DIR`. */
  namespace?: BundleNamespace;
  /**
   * Explicit opt-in stale-if-error cache (child tier): `/bundles/…` URLs
   * write through to disk on success and serve last-known-good bytes when
   * the origin fails. Never derived implicitly — a cache that activates
   * itself can serve pre-reset bytes after a deploy.
   */
  cacheDir?: string;
  /** Per-attempt deadline for idempotent GETs crossing the interceptor. */
  timeoutMs?: number;
}
/**
 * Installs the resolver as a global fetch interceptor — the one seam every
 * boot-time consumer shares (config manifest discovery, contract-type
 * fetches, orchestrator host loading, MF remoteEntry/identity probes) and
 * the SSR serving path. One layered resolution policy, as a single Effect
 * program on the managed runtime: staged disk → network → (explicitly
 * opted-in) stale-if-error. Own-namespace URLs resolve from the staged
 * directory and fall through to the network on a miss; a miss never touches
 * the write-through cache — for the own namespace the staged disk IS the
 * resilience artifact. Inert when neither a staged namespace nor an
 * explicit cache is configured.
 */
declare function installGlobalBundleFetch(options: BundleFetchOptions): BundleFetchHandle;
/**
 * Boot-time installer for the CLI and the host server: derives the own
 * namespace from `BOS_BUNDLE_DIR` plus the runtime identity
 * (`BOS_ACCOUNT`/`BOS_GATEWAY` registry env taking precedence over the
 * bos.config.json fields), and the stale-if-error cache from an explicit
 * `BOS_BUNDLE_CACHE_DIR` — never implicit. Tier auto-detection (ADR 0021):
 * an identity whose namespace is not actually staged under the bundle dir
 * drops to the registry tier — plain resilient network fetch — instead of
 * deterministically 404ing own-namespace URLs against a foreign image's
 * staged bytes. Never throws — a missing or malformed identity leaves the
 * default fetch in place.
 */
declare function installBundleFetchFromEnv(input: {
  configPath?: string | null;
}): BundleFetchHandle | null;
//#endregion
export { BundleFetchHandle, BundleFetchOptions, BundleNamespace, BundleReadError, BundleResolver, bundleUrlToLocalPath, bundleUrlToStagedPath, installBundleFetchFromEnv, installGlobalBundleFetch, resolveContained };
//# sourceMappingURL=resolver.d.mts.map