hyperbrane 0.1.2 → 0.2.0

package/dist/portal-gateway/api.d.ts

@@ -1,4 +1,6 @@
+import type { SandboxAccess } from "../sandbox/api.ts";
 import type { UpstreamDefinition } from "./upstream.ts";
+export { defineUpstream } from "./upstream.ts";
 export type Portal = {
     name: string;
     dimensionName: string;
@@ -6,33 +8,15 @@ export type Portal = {
 };
 export type Gateway = {
     name: string;
-    /**
-     * Registered when the gateway is created: the built-in upstreams (upstreams/) unless given, `[]`
-     * for none. A gateway that doesn't know an upstream passes its tokens to dimensions untouched.
-     */
     upstreams?: Upstream[];
 };
 export type Upstream = UpstreamDefinition;
-/**
- * Never the secret: "<upstream>.oauth" for a captured sign-in, "<upstream>.key.<key>" per API key,
- * with the key's fake, which is what a client in a dimension is given in place of the key.
- */
 export type GatewayCredential = {
     readonly name: string;
     readonly gatewayName: string;
     readonly type: "oauth" | "apiKey";
     readonly fake?: string;
 };
-/**
- * Applies to traffic arriving through the gateway's portals. "tcp://<address>:<port>" covers every
- * TCP connection by its destination, before any byte is sent: address is "*", an IPv4 address or a
- * CIDR, port is "*" or a number ("tcp://10.0.0.0/8:*", "tcp://*:22"). Anything else is a glob over
- * every HTTP(S) request's host:port/path?query, whatever its scheme: "https://github.com/*",
- * "http://github.com/*" and "github.com" all cover github.com over HTTP and HTTPS, since a mask
- * without a port matches any port and one without a path any path. "github.com:80/*" is plain HTTP
- * only; "*.github.com/api/*" the API on any subdomain. Rules are checked in name order and the first
- * match decides.
- */
 export type TrafficRule = {
     name: string;
     urlMask: string;
@@ -40,60 +24,45 @@ export type TrafficRule = {
     delayMs: number;
 };
 /** @sealed */
-export interface PortalGatewayClient {
-    /** POST /v1/gateways — also replaces a container made from an older gateway image, keeping its state. */
+export interface GatewayClient {
     createGateway(gateway: Gateway): Promise<Gateway>;
-    /** DELETE /v1/gateways/:gatewayName */
     destroyGateway(gatewayName: string): Promise<void>;
-    /** GET /v1/gateways */
     listGateways(): Promise<Gateway[]>;
-    /** POST /v1/gateways/:gatewayName/restart — resolves once it intercepts again; its portals are re-wired by the portal watcher. */
     restartGateway(gatewayName: string): Promise<void>;
-    /** GET /v1/gateways/:gatewayName/credentials */
+    endpoint(gatewayName: string, options?: {
+        ttlSeconds?: number;
+    }): Promise<SandboxAccess>;
     listCredentials(gatewayName: string): Promise<GatewayCredential[]>;
-    /** DELETE /v1/gateways/:gatewayName/credentials/:credentialName */
     deleteCredential(gatewayName: string, credentialName: string): Promise<void>;
-    /** PUT /v1/gateways/:gatewayName/upstreams/:upstreamName — adds or replaces the definition. */
     registerUpstream(gatewayName: string, upstream: Upstream): Promise<Upstream>;
-    /** GET /v1/gateways/:gatewayName/upstreams */
     listUpstreams(gatewayName: string): Promise<Upstream[]>;
-    /** DELETE /v1/gateways/:gatewayName/upstreams/:upstreamName — with its credentials. */
     removeUpstream(gatewayName: string, upstreamName: string): Promise<void>;
-    /**
-     * PUT /v1/gateways/:gatewayName/upstreams/:upstreamName/api-keys/:keyName — returns the key's fake,
-     * to give the client in the dimension (e.g. as its API key env var) in place of the key.
-     */
     setApiKey(gatewayName: string, upstreamName: string, keyName: string, key: string): Promise<{
         readonly fake: string;
     }>;
-    /** DELETE /v1/gateways/:gatewayName/upstreams/:upstreamName/api-keys/:keyName */
     deleteApiKey(gatewayName: string, upstreamName: string, keyName: string): Promise<void>;
-    /** POST /v1/gateways/:gatewayName/traffic-rules */
     createTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
-    /** PUT /v1/gateways/:gatewayName/traffic-rules/:ruleName */
     updateTrafficRule(gatewayName: string, rule: TrafficRule): Promise<TrafficRule>;
-    /** DELETE /v1/gateways/:gatewayName/traffic-rules/:ruleName */
     deleteTrafficRule(gatewayName: string, ruleName: string): Promise<void>;
-    /** GET /v1/gateways/:gatewayName/traffic-rules */
     listTrafficRules(gatewayName: string): Promise<TrafficRule[]>;
-    /** POST /v1/gateways/:gatewayName/traffic-rules/:ruleName/respond — releases the requests an ASK rule is holding. */
     trafficRuleRespond(gatewayName: string, ruleName: string, action: "ALLOW" | "DENY"): Promise<void>;
-    /** POST /v1/portals */
+}
+/** @sealed */
+export interface PortalClient {
     createPortal(portal: Portal): Promise<Portal>;
-    /** DELETE /v1/portals/:portalName */
     destroyPortal(portalName: string): Promise<void>;
-    /** GET /v1/portals */
     listPortals(): Promise<Portal[]>;
+    restorePortals(filter?: {
+        gatewayName?: string;
+        dimensionName?: string;
+    }): Promise<void>;
 }
-/** The request can't be satisfied as sent (bad name, unsupported action, ...). */
 export declare class GatewayInvalidError extends Error {
     name: string;
 }
-/** The name is taken with a different spec, or by a container hyperbrane doesn't own. */
 export declare class GatewayConflictError extends Error {
     name: string;
 }
-/** A gateway, rule, dimension or portal the request refers to doesn't exist. */
 export declare class GatewayNotFoundError extends Error {
     name: string;
 }

package/dist/portal-gateway/api.js

@@ -1,12 +1,10 @@
-/** The request can't be satisfied as sent (bad name, unsupported action, ...). */
+export { defineUpstream } from "./upstream.js";
 export class GatewayInvalidError extends Error {
     name = "GatewayInvalidError";
 }
-/** The name is taken with a different spec, or by a container hyperbrane doesn't own. */
 export class GatewayConflictError extends Error {
     name = "GatewayConflictError";
 }
-/** A gateway, rule, dimension or portal the request refers to doesn't exist. */
 export class GatewayNotFoundError extends Error {
     name = "GatewayNotFoundError";
 }

package/dist/portal-gateway/control.d.ts

@@ -0,0 +1,42 @@
+import { type ControlOptions } from "../lib/control.ts";
+import type { Sandbox, SandboxEndpoint } from "../sandbox/api.ts";
+import { type Gateway, type Portal, type TrafficRule, type Upstream } from "./api.ts";
+import type { ApiKeyCredential } from "./upstream.ts";
+export declare const GATEWAY_STATE_PATH = "/state";
+export declare function gatewayContainerName(gatewayName: string): string;
+export declare function gatewayCaCertificatePath(stateDirectory: string): string;
+export declare function portalEnv(): Record<string, string>;
+export type GatewayControl = ReturnType<typeof gatewayControl>;
+export declare function gatewayControl(host: Sandbox, ensureImage: () => Promise<unknown>, options?: ControlOptions): {
+    createGateway(gatewayName: string, upstreams: Upstream[]): Promise<void>;
+    destroyGateway(gatewayName: string): Promise<void>;
+    restartGateway(gatewayName: string): Promise<void>;
+    startTransport(gatewayName: string, endpoint: SandboxEndpoint, { restart, }: {
+        restart: boolean;
+    }): Promise<void>;
+    listGateways(): Promise<Gateway[]>;
+    registerUpstream(gatewayName: string, upstream: Upstream): Promise<void>;
+    listUpstreams(gatewayName: string): Promise<Upstream[]>;
+    removeUpstream(gatewayName: string, upstreamName: string): Promise<void>;
+    listCredentials(gatewayName: string): Promise<{
+        upstream: string;
+        oauth: boolean;
+        apiKeys: ApiKeyCredential | null;
+    }[]>;
+    removeOAuthCredential(gatewayName: string, upstreamName: string): Promise<void>;
+    setApiKey(gatewayName: string, upstreamName: string, keyName: string, key: string, fakeCharacters: string): Promise<string>;
+    deleteApiKey(gatewayName: string, upstreamName: string, keyName: string): Promise<void>;
+    createTrafficRule(gatewayName: string, rule: TrafficRule): Promise<void>;
+    updateTrafficRule(gatewayName: string, rule: TrafficRule): Promise<void>;
+    deleteTrafficRule(gatewayName: string, ruleName: string): Promise<void>;
+    listTrafficRules(gatewayName: string): Promise<TrafficRule[]>;
+    trafficRuleRespond(gatewayName: string, ruleName: string, action: "ALLOW" | "DENY"): Promise<void>;
+    createPortal(portal: Portal): Promise<void>;
+    destroyPortal(portalName: string): Promise<void>;
+    listPortals(): Promise<Portal[]>;
+    restorePortals({ gatewayName, dimensionName }: {
+        gatewayName?: string;
+        dimensionName?: string;
+    }): Promise<string>;
+};
+export declare const PORTAL_FUNCTIONS: string;