@le-space/core 0.1.0

package/README.md

@@ -0,0 +1,4 @@
+# @shared-aleph/core
+
+Framework-agnostic Aleph deployment and manifest logic will live here.
+

package/index.d.ts

@@ -0,0 +1,522 @@
+import * as _shared_aleph_shared_types from '@shared-aleph/shared-types';
+import { RootfsResolution, RootfsManifest, RootfsManifestState, CrnRecord, RootfsRequiredPortForward, PortForwardAggregate, PortForwardFlags, PortForwardAggregateEntry, MessageReference, InstanceExecution, MessageStatus, DeploymentInspectionResult, MessageInspectionResult, AlephBroadcastMessage, AlephBroadcastResponse, MessageSigner, MessageHasher, AlephAggregateContent, AlephInstanceContent, DeploymentResult, InstanceAllocation, InstanceRuntimeDetails, InstanceWebAccess, RuntimeDiagnostics, PortMapping } from '@shared-aleph/shared-types';
+
+declare const DEFAULT_ALEPH_CHANNEL = "TEST";
+
+declare const ITEM_HASH_RE: RegExp;
+declare const DEFAULT_ALEPH_API_HOST = "https://api2.aleph.im";
+declare const DEFAULT_IPFS_GATEWAY_BASE_URL = "https://ipfs.aleph.cloud/ipfs/";
+interface FetchLikeResponse {
+    ok: boolean;
+    status: number;
+    url?: string;
+    json(): Promise<unknown>;
+}
+type FetchLike = (url: string, init?: RequestInit) => Promise<FetchLikeResponse>;
+declare function validateRootfsManifest(manifest: RootfsManifest | null): RootfsManifestState;
+declare function verifyRootfsExists(itemHash: string, options: {
+    apiHost?: string;
+    fetch: FetchLike;
+}): Promise<boolean>;
+declare function probeRootfsGateway(cid: string, options: {
+    gatewayBaseUrl?: string;
+    fetch: FetchLike;
+}): Promise<Pick<RootfsResolution, 'gatewayStatus' | 'gatewayError' | 'gatewayUrl'>>;
+declare function resolveRootfsReference(itemHash: string, options: {
+    apiHost?: string;
+    gatewayBaseUrl?: string;
+    fetch: FetchLike;
+}): Promise<RootfsResolution | null>;
+
+declare const DEFAULT_CRN_LIST_URL = "https://crns-list.aleph.sh/crns.json";
+declare const DEFAULT_COUNTRY_LOOKUP_BASE_URL = "https://api.country.is";
+declare const DEFAULT_DNS_RESOLVE_URL = "https://dns.google/resolve";
+declare function fetchCrns(options: {
+    url?: string;
+    fetch: FetchLike;
+}): Promise<CrnRecord[]>;
+declare function enrichCrnsWithGeo(crns: ReadonlyArray<CrnRecord>, options: {
+    fetch: FetchLike;
+    dnsResolveUrl?: string;
+    countryLookupBaseUrl?: string;
+}): Promise<CrnRecord[]>;
+declare function listGeocodedCrns(options: {
+    fetch: FetchLike;
+    url?: string;
+    limit?: number;
+    dnsResolveUrl?: string;
+    countryLookupBaseUrl?: string;
+}): Promise<CrnRecord[]>;
+declare function rankCandidateCrns(crns: ReadonlyArray<CrnRecord>, options: {
+    fetch: FetchLike;
+    preferredCountryCode?: string;
+    geoLimit?: number;
+    excludedHashes?: string[];
+    dnsResolveUrl?: string;
+    countryLookupBaseUrl?: string;
+}): Promise<CrnRecord[]>;
+declare function selectPreferredCrn(crns: ReadonlyArray<CrnRecord>, options: {
+    fetch: FetchLike;
+    preferredCountryCode?: string;
+    geoLimit?: number;
+    excludedHashes?: string[];
+    dnsResolveUrl?: string;
+    countryLookupBaseUrl?: string;
+}): Promise<CrnRecord | null>;
+
+declare const DEFAULT_INSTANCE_PORT_FORWARDS: RootfsRequiredPortForward[];
+declare function normalizeExistingPortForwardEntry(entry: PortForwardAggregateEntry | null | undefined): Record<string, PortForwardFlags>;
+declare function requestedPortFlags(portForwards: ReadonlyArray<RootfsRequiredPortForward>): Record<string, PortForwardFlags>;
+declare function mergePortFlagMaps(existing: Record<string, PortForwardFlags>, requested: Record<string, PortForwardFlags>): Record<string, PortForwardFlags>;
+declare function mergeRequiredPortForwards(...groups: Array<ReadonlyArray<RootfsRequiredPortForward> | undefined>): RootfsRequiredPortForward[];
+declare function requiredInstancePortForwards(manifest: RootfsManifest | null): RootfsRequiredPortForward[];
+declare function portForwardLabel(entry: RootfsRequiredPortForward): string;
+declare function fetchPortForwardAggregate(address: string, options: {
+    apiHost?: string;
+    fetch: FetchLike;
+}): Promise<PortForwardAggregate>;
+
+type MessageEnvelope$1 = {
+    status?: unknown;
+    type?: unknown;
+    error_code?: unknown;
+    details?: unknown;
+    message?: {
+        type?: unknown;
+    } | null;
+    messages?: Array<{
+        type?: unknown;
+    }> | null;
+};
+type CrnExecutionV1Payload = {
+    networking?: {
+        ipv4?: unknown;
+        ipv6?: unknown;
+    } | null;
+};
+type CrnExecutionV2Payload = {
+    networking?: {
+        ipv4_network?: unknown;
+        host_ipv4?: unknown;
+        ipv6_network?: unknown;
+        ipv6_ip?: unknown;
+        ipv4_ip?: unknown;
+        proxy_url?: unknown;
+        proxyUrl?: unknown;
+        web_access_url?: unknown;
+        webAccessUrl?: unknown;
+        proxy_hostname?: unknown;
+        proxyHostname?: unknown;
+        domain?: unknown;
+        hostname?: unknown;
+        mapped_ports?: Record<string, {
+            host?: unknown;
+            tcp?: unknown;
+            udp?: unknown;
+        }> | null;
+    } | null;
+    web_access?: {
+        url?: unknown;
+        proxy_url?: unknown;
+        hostname?: unknown;
+        domain?: unknown;
+    } | null;
+    webAccess?: {
+        url?: unknown;
+        proxy_url?: unknown;
+        hostname?: unknown;
+        domain?: unknown;
+    } | null;
+    status?: {
+        defined_at?: unknown;
+        preparing_at?: unknown;
+        prepared_at?: unknown;
+        starting_at?: unknown;
+        started_at?: unknown;
+        stopping_at?: unknown;
+        stopped_at?: unknown;
+    } | null;
+    running?: unknown;
+};
+declare function normalizeMessageStatus(status: unknown): MessageStatus;
+declare function normalizeProxyUrl(value: unknown): string | null;
+declare function messageTypeFromEnvelope(payload: MessageEnvelope$1 | null): string | null;
+declare function extractReferenceHashes(details: unknown): string[];
+declare function describeRejectedDeployment(payload: MessageEnvelope$1, references: MessageReference[], rootfsRef?: string): string;
+declare function extractProxyUrl(item: CrnExecutionV2Payload, networking: CrnExecutionV2Payload['networking']): string | null;
+declare function normalizeExecution(item: CrnExecutionV1Payload | CrnExecutionV2Payload, crnUrl: string): InstanceExecution;
+
+type MessageEnvelope = {
+    status?: unknown;
+    type?: unknown;
+    error_code?: unknown;
+    details?: unknown;
+    message?: {
+        type?: unknown;
+    } | null;
+    messages?: Array<{
+        type?: unknown;
+    }> | null;
+};
+declare function fetchMessageEnvelope(itemHash: string, options: {
+    apiHost?: string;
+    fetch: FetchLike;
+}): Promise<MessageEnvelope | null>;
+declare function inspectMessageResult(itemHash: string, options: {
+    apiHost?: string;
+    fetch: FetchLike;
+    label?: string;
+}): Promise<MessageInspectionResult>;
+declare function inspectDeploymentResult(itemHash: string, options: {
+    rootfsRef?: string;
+    apiHost?: string;
+    fetch: FetchLike;
+}): Promise<DeploymentInspectionResult>;
+declare function waitForDeploymentResult(itemHash: string, options: {
+    rootfsRef?: string;
+    apiHost?: string;
+    fetch: FetchLike;
+    attempts?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<DeploymentInspectionResult>;
+
+interface JsonFetchLikeResponse {
+    ok: boolean;
+    status: number;
+    json(): Promise<unknown>;
+}
+type JsonFetchLike = (url: string, init?: RequestInit) => Promise<JsonFetchLikeResponse>;
+declare function signaturePayload(message: Pick<AlephBroadcastMessage, 'chain' | 'sender' | 'type' | 'item_hash'>): string;
+declare function signAlephMessage(unsignedMessage: Omit<AlephBroadcastMessage, 'signature'>, signer: MessageSigner): Promise<AlephBroadcastMessage>;
+declare function normalizeBroadcastStatus(httpStatus: number, responseStatus: unknown): MessageStatus;
+declare function isInvalidMessageFormatResponse(response: {
+    status: number;
+}, payload: AlephBroadcastResponse): boolean;
+declare function isRetryableBroadcastFailure(response: {
+    status: number;
+}, payload: AlephBroadcastResponse): boolean;
+declare function postBroadcastPayload(body: Record<string, unknown>, options: {
+    apiHost?: string;
+    fetch: JsonFetchLike;
+}): Promise<{
+    response: AlephBroadcastResponse;
+    httpStatus: number;
+}>;
+declare function broadcastAlephMessage(message: AlephBroadcastMessage, options: {
+    apiHost?: string;
+    sync?: boolean;
+    fetch: JsonFetchLike;
+}): Promise<{
+    response: AlephBroadcastResponse;
+    httpStatus: number;
+}>;
+
+declare function createUnsignedForgetMessage(args: {
+    sender: string;
+    hashes?: string[];
+    aggregates?: string[];
+    reason?: string;
+    hasher: MessageHasher;
+    channel?: string;
+    now?: number;
+}): Promise<Omit<AlephBroadcastMessage, 'signature'>>;
+declare function forgetAlephMessages(args: {
+    sender: string;
+    hashes?: string[];
+    aggregates?: string[];
+    reason?: string;
+    signer: MessageSigner;
+    hasher: MessageHasher;
+    fetch: JsonFetchLike;
+    channel?: string;
+    apiHost?: string;
+    sync?: boolean;
+    now?: number;
+}): Promise<{
+    sender: string;
+    itemHash: string;
+    response: _shared_aleph_shared_types.AlephBroadcastResponse;
+    httpStatus: number;
+    status: _shared_aleph_shared_types.MessageStatus;
+}>;
+declare function cleanupFailedDeployment(args: {
+    sender: string;
+    instanceItemHash: string;
+    reason?: string;
+    signer: MessageSigner;
+    hasher: MessageHasher;
+    fetch: JsonFetchLike;
+    channel?: string;
+    apiHost?: string;
+}): Promise<{
+    sender: string;
+    itemHash: string;
+    response: _shared_aleph_shared_types.AlephBroadcastResponse;
+    httpStatus: number;
+    status: _shared_aleph_shared_types.MessageStatus;
+} | {
+    error: string;
+}>;
+
+declare const SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY = "uc-go-peer-successful-deployments";
+interface RetentionRecord {
+    instance_item_hash: string;
+    rootfs_item_hash: string;
+    site_item_hash: string;
+    rootfs_cid: string;
+    site_url: string;
+    relay_peer_id: string;
+    rootfs_version: string;
+    deployed_at: string;
+    vm_name: string;
+}
+declare function fetchAggregateKey(args: {
+    address: string;
+    key: string;
+    fetch: JsonFetchLike;
+    apiHost?: string;
+}): Promise<unknown>;
+declare function publishAggregateKey(args: {
+    sender: string;
+    key: string;
+    content: Record<string, unknown>;
+    signer: MessageSigner;
+    hasher: MessageHasher;
+    fetch: JsonFetchLike;
+    channel?: string;
+    apiHost?: string;
+    now?: number;
+}): Promise<{
+    itemHash: string;
+    status: _shared_aleph_shared_types.MessageStatus;
+    response: _shared_aleph_shared_types.AlephBroadcastResponse;
+    httpStatus: number;
+}>;
+declare function retainSuccessfulDeployments(args: {
+    sender: string;
+    currentRecord: unknown;
+    keepCount: number;
+    signer: MessageSigner;
+    hasher: MessageHasher;
+    fetch: JsonFetchLike;
+    aggregateKey?: string;
+    extraForgetHashes?: string[];
+    reason?: string;
+    channel?: string;
+    apiHost?: string;
+    now?: number;
+}): Promise<{
+    sender: string;
+    aggregateKey: string;
+    keepCount: number;
+    aggregatePublication: {
+        itemHash: string;
+        status: _shared_aleph_shared_types.MessageStatus;
+        response: _shared_aleph_shared_types.AlephBroadcastResponse;
+        httpStatus: number;
+    };
+    retainedRecords: RetentionRecord[];
+    prunedRecords: RetentionRecord[];
+    forgetHashes: string[];
+    forgetResult: {
+        sender: string;
+        itemHash: string;
+        response: _shared_aleph_shared_types.AlephBroadcastResponse;
+        httpStatus: number;
+        status: _shared_aleph_shared_types.MessageStatus;
+    } | null;
+}>;
+
+declare function createPortForwardAggregateContent(args: {
+    sender: string;
+    instanceItemHash: string;
+    requestedPorts: ReadonlyArray<RootfsRequiredPortForward>;
+    existingAggregate?: PortForwardAggregate;
+    now?: number;
+}): AlephAggregateContent<PortForwardAggregate>;
+declare function createUnsignedAggregateMessage(args: {
+    sender: string;
+    content: AlephAggregateContent<PortForwardAggregate>;
+    hasher: MessageHasher;
+    channel?: string;
+    now?: number;
+}): Promise<Omit<AlephBroadcastMessage, 'signature'>>;
+declare function ensureInstancePortForwards(args: {
+    sender: string;
+    instanceItemHash: string;
+    manifest: RootfsManifest | null;
+    signer: MessageSigner;
+    hasher: MessageHasher;
+    fetch: JsonFetchLike;
+    channel?: string;
+    apiHost?: string;
+    sync?: boolean;
+}): Promise<{
+    aggregateItemHash: string;
+    aggregateStatus: MessageStatus;
+    requestedPorts: RootfsRequiredPortForward[];
+}>;
+
+declare const SSH_PUBLIC_KEY_PATTERN: RegExp;
+declare function normalizeSshPublicKey(value: string): string;
+declare function isValidSshPublicKey(value: string): boolean;
+declare function createReleaseMetadata(name: string, rootfsVersion: string, deployer?: string): {
+    name: string;
+    rootfs_version: string;
+    deployer: string;
+};
+declare function createInstanceContent(args: {
+    address: string;
+    name: string;
+    sshPublicKey: string;
+    rootfsItemHash: string;
+    rootfsSizeMiB: number;
+    vcpus: number;
+    memoryMiB: number;
+    seconds?: number;
+    rootfsVersion?: string;
+    crnHash?: string;
+    deployer?: string;
+    now?: number;
+}): AlephInstanceContent;
+declare function createUnsignedInstanceMessage(args: {
+    sender: string;
+    content: AlephInstanceContent;
+    hasher: MessageHasher;
+    channel?: string;
+    now?: number;
+}): Promise<Omit<AlephBroadcastMessage, 'signature'>>;
+declare function deployInstance(args: {
+    sender: string;
+    content: AlephInstanceContent;
+    hasher: MessageHasher;
+    signer: MessageSigner;
+    fetch: (url: string, init?: RequestInit) => Promise<{
+        ok: boolean;
+        status: number;
+        json(): Promise<unknown>;
+    }>;
+    apiHost?: string;
+    channel?: string;
+    sync?: boolean;
+    now?: number;
+}): Promise<DeploymentResult>;
+
+declare const DEFAULT_SCHEDULER_ALLOCATION_URL = "https://scheduler.api.aleph.cloud/api/v0/allocation";
+declare const DEFAULT_TWO_N_SIX_HASH_URL = "https://api.2n6.me/api/hash";
+type CrnExecutionLookup = {
+    version: 'v1' | 'v2';
+    payload: Record<string, unknown> | null;
+    requestUrl: string;
+};
+declare function findCrnByHash(crns: ReadonlyArray<CrnRecord>, crnHash: string): CrnRecord | null;
+declare function fetchSchedulerAllocation(itemHash: string, options: {
+    fetch: FetchLike;
+    schedulerAllocationUrl?: string;
+}): Promise<InstanceAllocation | null>;
+declare function fetch2n6WebAccessUrl(itemHash: string, options: {
+    fetch: FetchLike;
+    twoN6HashUrl?: string;
+}): Promise<InstanceWebAccess | null>;
+declare function fetchCrnExecutionMap(crnUrl: string, options: {
+    fetch: FetchLike;
+}): Promise<CrnExecutionLookup>;
+declare function describeRuntimeAvailability(runtime: {
+    allocation?: InstanceAllocation | null;
+    execution?: InstanceRuntimeDetails['execution'];
+    webAccess?: InstanceWebAccess | null;
+    hostIpv4?: string | null;
+    ipv6?: string | null;
+    proxyUrl?: string | null;
+    mappedPorts?: Record<string, unknown>;
+}): RuntimeDiagnostics;
+declare function fetchVmRuntime(args: {
+    itemHash: string;
+    fetch: FetchLike;
+    crns?: CrnRecord[];
+    crnHash?: string;
+    crnListUrl?: string;
+    schedulerAllocationUrl?: string;
+    twoN6HashUrl?: string;
+}): Promise<Omit<InstanceRuntimeDetails, 'messageStatus'>>;
+declare function waitForVmRuntime(args: {
+    itemHash: string;
+    fetch: FetchLike;
+    crns?: CrnRecord[];
+    crnHash?: string;
+    crnListUrl?: string;
+    schedulerAllocationUrl?: string;
+    twoN6HashUrl?: string;
+    attempts?: number;
+    delayMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<Omit<InstanceRuntimeDetails, 'messageStatus'>>;
+
+type TcpProbeResult = {
+    ok: boolean | null;
+    error?: string;
+};
+type HttpProbeResult = {
+    ok: boolean;
+    status?: number;
+    url?: string;
+    error?: string;
+};
+declare function notifyCrnAllocation(args: {
+    crnUrl: string | null | undefined;
+    itemHash: string;
+    fetch: FetchLike;
+}): Promise<{
+    status: 'confirmed' | 'unconfirmed' | 'skipped';
+    reason?: string;
+    payload?: unknown;
+}>;
+declare function waitForSetupEndpoint(args: {
+    hostIpv4: string;
+    setupPort: number;
+    fetch: FetchLike;
+    attempts?: number;
+    delayMs?: number;
+    httpTimeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<HttpProbeResult>;
+declare function configureUcGoPeer(args: {
+    hostIpv4: string;
+    setupPort: number;
+    publicIpv6?: string | null;
+    tcpPort?: number | null;
+    wsPort?: number | null;
+    udpPort?: number | null;
+    quicPort?: number | null;
+    webrtcPort?: number | null;
+    proxyUrl?: string | null;
+    fetch: FetchLike;
+    timeoutMs?: number;
+}): Promise<unknown>;
+declare function fetchUcGoPeerMetadata(args: {
+    hostIpv4: string;
+    setupPort: number;
+    fetch: FetchLike;
+    attempts?: number;
+    delayMs?: number;
+    timeoutMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<unknown>;
+declare function verifyUcGoPeerReachability(args: {
+    hostIpv4?: string | null;
+    mappedPorts?: Record<string, PortMapping>;
+    proxyUrl?: string | null;
+    verifyProxyHttp?: boolean;
+    skipInternalPorts?: string[];
+    tcpTimeoutMs?: number;
+    httpTimeoutMs?: number;
+    fetch: FetchLike;
+    tcpProbe: (host: string, port: number, timeoutMs?: number) => Promise<TcpProbeResult>;
+    httpProbe?: (url: string, timeoutMs?: number) => Promise<HttpProbeResult>;
+}): Promise<{
+    ok: boolean;
+    checks: Record<string, Record<string, unknown>>;
+}>;
+
+export { DEFAULT_ALEPH_API_HOST, DEFAULT_ALEPH_CHANNEL, DEFAULT_COUNTRY_LOOKUP_BASE_URL, DEFAULT_CRN_LIST_URL, DEFAULT_DNS_RESOLVE_URL, DEFAULT_INSTANCE_PORT_FORWARDS, DEFAULT_IPFS_GATEWAY_BASE_URL, DEFAULT_SCHEDULER_ALLOCATION_URL, DEFAULT_TWO_N_SIX_HASH_URL, type FetchLike, type FetchLikeResponse, type HttpProbeResult, ITEM_HASH_RE, type JsonFetchLike, type JsonFetchLikeResponse, type RetentionRecord, SSH_PUBLIC_KEY_PATTERN, SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY, type TcpProbeResult, broadcastAlephMessage, cleanupFailedDeployment, configureUcGoPeer, createInstanceContent, createPortForwardAggregateContent, createReleaseMetadata, createUnsignedAggregateMessage, createUnsignedForgetMessage, createUnsignedInstanceMessage, deployInstance, describeRejectedDeployment, describeRuntimeAvailability, enrichCrnsWithGeo, ensureInstancePortForwards, extractProxyUrl, extractReferenceHashes, fetch2n6WebAccessUrl, fetchAggregateKey, fetchCrnExecutionMap, fetchCrns, fetchMessageEnvelope, fetchPortForwardAggregate, fetchSchedulerAllocation, fetchUcGoPeerMetadata, fetchVmRuntime, findCrnByHash, forgetAlephMessages, inspectDeploymentResult, inspectMessageResult, isInvalidMessageFormatResponse, isRetryableBroadcastFailure, isValidSshPublicKey, listGeocodedCrns, mergePortFlagMaps, mergeRequiredPortForwards, messageTypeFromEnvelope, normalizeBroadcastStatus, normalizeExecution, normalizeExistingPortForwardEntry, normalizeMessageStatus, normalizeProxyUrl, normalizeSshPublicKey, notifyCrnAllocation, portForwardLabel, postBroadcastPayload, probeRootfsGateway, publishAggregateKey, rankCandidateCrns, requestedPortFlags, requiredInstancePortForwards, resolveRootfsReference, retainSuccessfulDeployments, selectPreferredCrn, signAlephMessage, signaturePayload, validateRootfsManifest, verifyRootfsExists, verifyUcGoPeerReachability, waitForDeploymentResult, waitForSetupEndpoint, waitForVmRuntime };