@openmbee/opensysml 0.9.1

package/dist/node/binary.d.ts

@@ -0,0 +1,127 @@
+import { OpenSysMLError } from "../core/errors.js";
+import { ReleaseSigner } from "./signing.js";
+/** Names a build of sysml-grpc to use, in place of any package, download or cache. */
+export declare const BINARY_ENV = "OPENSYSML_BINARY";
+/** Names the release to download, when the caller asks for none. */
+export declare const VERSION_ENV = "OPENSYSML_GRPC_VERSION";
+/** Overrides the repository releases are downloaded from. */
+export declare const REPO_ENV = "OPENSYSML_GITHUB_REPO";
+/** Repository whose unpinned downloads may be accepted (`1` for any): same-origin trust. */
+export declare const ALLOW_UNPINNED_ENV = "OPENSYSML_ALLOW_UNPINNED_DOWNLOAD";
+/** Repository releases are downloaded from unless $OPENSYSML_GITHUB_REPO names another. */
+export declare const DEFAULT_GITHUB_REPO = "Open-MBEE/OpenSysML";
+/** Origin a release publishes its assets at, and the API the latest tag is read from. */
+export declare const RELEASES_BASE_URL = "https://github.com";
+export declare const API_BASE_URL = "https://api.github.com";
+/** Per-request timeout: this runs while a service is starting, so it must not hang. */
+export declare const NETWORK_TIMEOUT_MS = 15000;
+/** The pinned digest table, keyed by repository, release tag and asset name. */
+export type PinnedDigests = Readonly<Record<string, Readonly<Record<string, Readonly<Record<string, string>>>>>>;
+/** Where a binary was found, and how. */
+export interface Binary {
+    path: string;
+    /** Human-readable provenance, used in error messages and ServerInfo.origin. */
+    source: string;
+}
+/** What the cached binary was downloaded from, shared with the Python client. */
+export interface CacheMetadata {
+    version: string;
+    sha256: string;
+    repo: string;
+}
+/** How a release is downloaded. Every field has a default; tests supply the seams. */
+export interface DownloadOptions {
+    /** Release tag to install, or 'latest'; $OPENSYSML_GRPC_VERSION when omitted. */
+    version?: string;
+    /** Repository to download from; $OPENSYSML_GITHUB_REPO or the default when omitted. */
+    githubRepo?: string;
+    /** Origin release assets are published at. */
+    releasesBaseUrl?: string;
+    /** GitHub API the latest release tag is read from. */
+    apiBaseUrl?: string;
+    /** Directory the binary and its metadata are cached in. */
+    cacheDir?: string;
+    /** Platform the release asset is chosen for; this process's by default. */
+    platform?: string;
+    /** Architecture the release asset is chosen for; this process's by default. */
+    arch?: string;
+    /** Identity the release manifest's signature must carry; the pinned one when omitted. */
+    signer?: ReleaseSigner;
+    /** Digest table to verify against; the one this package ships when omitted. */
+    pinnedDigests?: PinnedDigests;
+    /** Where warnings go; Node's process warnings when omitted. */
+    warn?: (message: string) => void;
+}
+/** No usable binary was found, and none could be fetched. */
+export declare class BinaryNotFoundError extends OpenSysMLError {
+}
+/**
+ * The digests this package ships, synced from client/release-digests.json: a pin
+ * resolved from outside the published artifact would not be a pin.
+ */
+export declare const PINNED_SHA256: PinnedDigests;
+/** The npm package that carries the service binary for this platform. */
+export declare function platformPackage(platform?: string, arch?: string): string;
+/** The binary's file name on this platform. */
+export declare function binaryName(platform?: string): string;
+/** Repository releases are downloaded from. */
+export declare function defaultGithubRepo(): string;
+/** Name a release publishes the service binary for a platform under. */
+export declare function releaseAssetName(platform?: string, arch?: string): string;
+/** The digest this release of the client pins for a release asset. */
+export declare function pinnedDigest(version: string, asset: string, githubRepo?: string, table?: PinnedDigests): string | undefined;
+/** Whether an unpinned download from a repository may fall back to same-origin trust. */
+export declare function unpinnedDownloadsAllowed(githubRepo?: string): boolean;
+/**
+ * The digest a download must have: the pin wherever there is one, else the signed
+ * manifest's, else nothing, unless same-origin trust was allowed explicitly.
+ */
+export declare function expectedDigest(request: {
+    version: string;
+    asset: string;
+    servedDigest: string;
+    githubRepo?: string;
+    /** Digest from the release's signed checksum manifest, once its signature verified. */
+    verifiedDigest?: string;
+    /** Why there is no verified digest, said in the refusal when there is no pin either. */
+    unverifiedReason?: string;
+    pinnedDigests?: PinnedDigests;
+    warn?: (message: string) => void;
+}): string;
+/** URL a release publishes an asset at. */
+export declare function releaseDownloadUrl(version: string, asset: string, options?: DownloadOptions): string;
+/** The digest for an asset from the release's signed checksum manifest. */
+export declare function signedManifestDigest(version: string, asset: string, options?: DownloadOptions): Promise<string>;
+/** Resolve the tag of the repository's latest published release. */
+export declare function resolveLatestVersion(options?: DownloadOptions): Promise<string>;
+/** Path the downloaded binary is cached at, shared with the Python client. */
+export declare function cachedBinaryPath(options?: DownloadOptions): string;
+/** Path of the record of which release the cached binary was downloaded from. */
+export declare function metadataPath(options?: DownloadOptions): string;
+/** Read the record beside the cached binary, or nothing when it says nothing. */
+export declare function readMetadata(options?: DownloadOptions): Promise<CacheMetadata | undefined>;
+/** Record which release of which repository the cached binary is, and its digest. */
+export declare function writeMetadata(version: string, sha256: string, options?: DownloadOptions): Promise<void>;
+/**
+ * Release tag the cached binary was downloaded from, if from this repository: the
+ * digest is re-checked, so a binary swapped in by hand does not answer for it.
+ */
+export declare function cachedRelease(options?: DownloadOptions): Promise<string | undefined>;
+/**
+ * Why the cached binary is not the release asked for, or nothing when it is: an
+ * older cache would otherwise fail on whatever that build cannot do.
+ */
+export declare function staleCacheReason(version: string | undefined, options?: DownloadOptions): Promise<string | undefined>;
+/**
+ * Download a release's service binary and install it in the cache, replacing what is
+ * there only once the bytes match the digest expected of them.
+ */
+export declare function downloadBinary(options?: DownloadOptions): Promise<string>;
+/** Whether a file's SHA-256 digest is the one expected of it. */
+export declare function verifyChecksum(path: string, expectedSha256: string): Promise<boolean>;
+/**
+ * Finds a sysml-grpc binary: $OPENSYSML_BINARY, then the platform package, then a
+ * release download into the cache the Python client shares, then $PATH. A release is
+ * downloaded only when one is asked for, by `version` or $OPENSYSML_GRPC_VERSION.
+ */
+export declare function resolveBinary(options?: DownloadOptions): Promise<Binary>;