dsh-mobile 0.6.2 → 0.6.4

package/lib/index.d.mts

@@ -229,6 +229,37 @@ export declare class RequestTrustPolicy {
   canonicalOrigin(header: string | undefined): string | undefined;
 }
 //#endregion
+//#region src/extension-worker-config.d.ts
+/** Operator-owned limits for opt-in local extension worker execution. */
+interface HostExecutionConfig {
+  readonly mode?: 'in-process' | 'worker';
+  /** Apply worker mode only to these exact local ids; omitted selects every local host. */
+  readonly extensions?: readonly string[] | undefined;
+  readonly maxWorkers?: number;
+  readonly maxRegistrations?: number;
+  readonly maxOldGenerationSizeMb?: number;
+  readonly maxYoungGenerationSizeMb?: number;
+  readonly stackSizeMb?: number;
+  readonly activationTimeoutMs?: number;
+  readonly operationTimeoutMs?: number;
+  readonly cancelGraceMs?: number;
+  readonly streamCancelGraceMs?: number;
+  readonly disposeGraceMs?: number;
+  readonly resultMaxBytes?: number;
+  readonly streamWindowBytes?: number;
+  readonly streamChunkBytes?: number;
+  readonly streamAggregateBytes?: number;
+  readonly logWindowMs?: number;
+  readonly logMessagesPerWindow?: number;
+  readonly logMessageBytes?: number;
+}
+/** Complete settings passed to each owned worker; Node limits do not isolate filesystem access. */
+interface ResolvedHostExecutionConfig extends Required<Omit<HostExecutionConfig, 'extensions'>> {
+  readonly extensions: readonly string[] | undefined;
+}
+/** Resolve configuration once; reject malformed modes, ids and incoherent stream windows. */
+export declare function resolveHostExecution(raw: unknown): ResolvedHostExecutionConfig;
+//#endregion
 //#region src/config.d.ts
 /** Optional compression for exact, already authorized WebSocket paths. */
 interface WebSocketCompressionConfig {
@@ -264,6 +295,8 @@ interface DisabledTlsConfig {
 type TlsConfig = ProvidedTlsConfig | DisabledTlsConfig;
 /** Operator-facing plugin configuration. */
 interface PluginConfig {
+  /** Local host execution mode and owned worker budgets; defaults to in-process. */
+  hostExecution?: HostExecutionConfig;
   /** Optional setup JSON written by the packaged CLI. */
   setupFile?: string;
   /** Preferred HTTPS origin used to derive the public authority and listener port. */
@@ -319,6 +352,7 @@ interface PluginConfig {
 }
 /** Resolved, validated security and resource limits. */
 interface ResolvedGatewayConfig {
+  readonly hostExecution: ResolvedHostExecutionConfig;
   readonly listenHost: string;
   readonly listenPort: number;
   readonly upstreamOrigin: URL;
@@ -431,8 +465,8 @@ export declare class JsonMobileAccessControlStore implements MobileAccessControl
   private readonly file;
   private readonly initiallyEnabled;
   constructor(file: string, initiallyEnabled: boolean);
-  /** Avoid writing an absent already-disabled state without changing recovery of existing files. */
-  disableIfPresent(): Promise<void>;
+  /** Disable an existing preference, returning the state only after private-file preparation completes. */
+  disableIfPresent(): Promise<MobileAccessControlState>;
   load(): Promise<MobileAccessControlState>;
   save(state: MobileAccessControlState): Promise<void>;
 }
@@ -519,6 +553,117 @@ export declare class WebSocketPathStore {
   replace(paths: readonly string[]): Promise<string[]>;
 }
 //#endregion
+//#region src/extension-worker-protocol.d.ts
+/** Metadata for one action, crossing the boundary without its functions. */
+interface WorkerActionMetadata {
+  readonly name: string;
+  readonly timeoutMs?: number;
+}
+/** Metadata for one route, crossing the boundary without its functions. */
+interface WorkerRouteMetadata {
+  readonly method: string;
+  readonly path: string;
+  readonly kind?: 'exact' | 'prefix';
+  readonly timeoutMs?: number;
+}
+//#endregion
+//#region src/extension-worker.d.ts
+/** JSON bytes serialized and size-checked inside the worker. */
+declare class PreparedJsonResult {
+  readonly bytes: Buffer;
+  constructor(bytes: Buffer);
+}
+/** Worker context is logger-only, never a Cordis Context or service proxy. */
+type WorkerParentLogger = Record<'debug' | 'info' | 'warn' | 'error', (...args: unknown[]) => void>;
+/** Every thread counts until actual exit, including activation, retirement and termination. */
+declare class ExtensionWorkerBudget {
+  readonly maximum: number;
+  private count;
+  constructor(maximum: number);
+  get current(): number;
+  reserve(): () => void;
+}
+interface ExtensionWorkerHostOptions {
+  readonly workerModule: string | URL;
+  readonly hostFile: string;
+  readonly manifest: LocalExtensionManifest;
+  readonly generation: string;
+  readonly logger: WorkerParentLogger;
+  readonly activationTimeoutMs?: number;
+  readonly limits?: HostExecutionConfig;
+  readonly budget?: ExtensionWorkerBudget;
+  readonly onUnavailable?: (error: MobileExtensionError) => void;
+}
+interface ExtensionWorkerActivation {
+  readonly runtimeId: string;
+  readonly actions: readonly WorkerActionMetadata[];
+  readonly routes: readonly WorkerRouteMetadata[];
+}
+declare class ExtensionWorkerHost {
+  private readonly options;
+  private readonly limits;
+  private readonly worker;
+  private readonly pending;
+  private readonly routePending;
+  private readonly streams;
+  private readonly detachedRoutes;
+  private readonly executionGrace;
+  private readonly exited;
+  private readonly unavailableController;
+  private termination;
+  private activation;
+  private dead;
+  private disposed;
+  private maxBufferedBytes;
+  private cancelledStreams;
+  private logWindowStart;
+  private logCount;
+  private stdioBytes;
+  private stdioResume;
+  constructor(options: ExtensionWorkerHostOptions);
+  /** A stopped generation never silently respawns. */
+  available(): boolean;
+  /** Activate once and receive executable-free registration metadata. */
+  activate(): Promise<ExtensionWorkerActivation>;
+  actionMetadata(): readonly WorkerActionMetadata[];
+  routeMetadata(): readonly WorkerRouteMetadata[];
+  /** Underlying action: settles only when execution completes or the thread exits. */
+  invokeExecution(action: string, input: unknown, caller: {
+    readonly signal: AbortSignal;
+    readonly deviceId: string;
+  }): Promise<PreparedJsonResult>;
+  /** Direct caller budget; service dispatch observes invokeExecution separately. */
+  invoke(action: string, input: unknown, caller: {
+    readonly signal: AbortSignal;
+    readonly deviceId: string;
+  }): Promise<PreparedJsonResult>;
+  /** Underlying route: late streams are cancelled and observed to confirmed end. */
+  handleRouteExecution(routeIndex: number, request: MobileRouteRequest): Promise<MobileRouteResponse>;
+  /** Handler budget ends at stream-start; stream lifetime remains cancellation-bound. */
+  handleRoute(routeIndex: number, request: MobileRouteRequest): Promise<MobileRouteResponse>;
+  private callerBudget;
+  streamStats(): {
+    readonly activeStreams: number;
+    readonly maxBufferedBytes: number;
+    readonly cancelledStreams: number;
+    readonly bufferedBytes: number;
+  };
+  /** Graceful effects cleanup followed by termination; completion requires actual exit. */
+  dispose(): Promise<void>;
+  whenExited(): Promise<void>;
+  /** Stop admission now, retain execution/budget ownership until confirmed thread exit. */
+  terminate(reason: string): Promise<void>;
+  private unavailable;
+  private markUnavailable;
+  private armExecutionGrace;
+  private settleExecutionGrace;
+  private post;
+  private handleMessage;
+  private totalUnacked;
+  private openStream;
+  private cancelStream;
+}
+//#endregion
 //#region src/extensions.d.ts
 /** Maximum sizes enforced at the local-extension filesystem boundary. */
 export declare const EXTENSION_LIMITS: Readonly<{
@@ -625,6 +770,26 @@ interface ActiveLocalExtension {
   readonly controller: AbortController;
   readonly cleanups: readonly (() => void | Promise<void>)[];
   readonly digest: string;
+  readonly worker?: ExtensionWorkerHost;
+}
+/** Local execution options; the packaged worker entry is used unless a test supplies an override. */
+interface LocalExecutionOptions {
+  readonly hostExecution?: HostExecutionConfig & {
+    readonly workerModule?: string;
+  };
+  readonly workerBudget?: ExtensionWorkerBudget;
+}
+/** Worker-host API: logger-only context, with no Cordis services or registrations crossing threads. */
+interface MobileWorkerHostApi {
+  readonly manifest: LocalExtensionManifest;
+  readonly context: {
+    readonly logger: WorkerParentLogger;
+  };
+  readonly schema: typeof z;
+  readonly signal: AbortSignal;
+  action(name: string, spec: MobileHostAction): void;
+  route(spec: MobileHostRoute): void;
+  effect(setup: () => void | (() => void | Promise<void>) | Promise<void | (() => void | Promise<void>)>): void;
 }
 /** Validate a stable extension id. */
 export declare function assertExtensionId(value: unknown): string;
@@ -647,6 +812,11 @@ export declare class MobileAccessService extends Service {
   private localRefreshAbort;
   private localLifecycle;
   private localClosed;
+  private localExecution;
+  private localExecutionKey;
+  private workerBudget;
+  private readonly disposal;
+  private readonly recoveries;
   constructor(ctx: Context);
   /** Register a normal Cordis extension and return an idempotent disposer. */
   registerExtension(definition: MobileExtensionDefinition): () => void;
@@ -659,6 +829,23 @@ export declare class MobileAccessService extends Service {
   manifest(): readonly MobileExtensionClientEntry[];
   /** Return loaded and failed local extension counts without exposing host errors. */
   status(): MobileExtensionStatus;
+  /** Local Host status does not reveal filesystem paths, credentials or extension errors. */
+  hostStatus(): {
+    readonly hosts: readonly {
+      readonly id: string;
+      readonly name: string;
+      readonly mode: 'worker' | 'in-process';
+      readonly state: 'ready' | 'unavailable';
+      readonly generation: string;
+    }[];
+    readonly limits: {
+      readonly maxWorkers: number;
+      readonly workers: number;
+    };
+  };
+  /** Explicitly replace one unavailable worker without replaying requests or changing its files. */
+  recoverExtension(id: string): Promise<void>;
+  private queueDisposal;
   /** Locate one active extension. */
   extension(id: string, generation?: string): MobileExtensionDefinition | ActiveLocalExtension | undefined;
   /** Return the active local generation signal for gateway cancellation wiring. */
@@ -683,7 +870,7 @@ export declare class MobileAccessService extends Service {
   /** Match one route and invoke it with a generation-bound abort signal. */
   route(id: string, method: string, pathname: string, request: MobileRouteRequest, generation?: string): Promise<MobileRouteResponse>;
   /** Start the local directory watcher; an absent directory is intentionally inert. */
-  startLocal(root: string, context: Context): Promise<void>;
+  startLocal(root: string, context: Context, options?: LocalExecutionOptions): Promise<void>;
   /** Stop the watcher and abort every local host generation. */
   stopLocal(): Promise<void>;
   /** Refresh all local extensions atomically; failures keep the previous snapshot. */
@@ -942,6 +1129,7 @@ export declare class FrpComponentManager {
   readonly componentStorage: string;
   readonly logRoot: string;
   private readonly stagingRoot;
+  private readonly stateDirectory;
   private readonly artifact;
   private readonly fetchArtifact;
   private readonly extractArtifact;
@@ -1146,6 +1334,7 @@ export declare function createFrpcToml(settings: FrpSettings, localPort: number,
 export declare function createFrpServerTemplate(settings: FrpSettings): string;
 /** Owns private FRP settings and generation-specific frpc configuration. */
 export declare class FrpConfigStore {
+  private readonly ownedRoot;
   readonly stateRoot: string;
   readonly settingsFile: string;
   readonly runtimeConfigFile: string;
@@ -1159,7 +1348,7 @@ export declare class FrpConfigStore {
   readonly proxyName: string;
   private settingsValue;
   private errorCode;
-  constructor(stateDirectory: string, proxyName?: string);
+  constructor(stateDirectory: string, proxyName?: string, ownedRoot?: string);
   /** Load private settings while rejecting links, oversized files, and unknown fields. */
   initialize(): Promise<void>;
   /**
@@ -1372,14 +1561,14 @@ export declare function frpIngressPaths(stateFile: string): FrpIngressPaths;
  * replaced silently. The leaf is re-signed when expiring or no longer valid for
  * the public IPv4, and the running gateway reloads it after a renewal check.
  */
-export declare function ensureFrpIngressCertificate(settings: FrpSettings, stateFile: string, now?: number, expectedCaFingerprint?: string): Promise<FrpIngressCertificate>;
+export declare function ensureFrpIngressCertificate(settings: FrpSettings, stateFile: string, now?: number, expectedCaFingerprint?: string, ownedRoot?: string): Promise<FrpIngressCertificate>;
 /**
  * Build the read-only self-check payload shown in the desktop panel.
  *
  * No secret ever leaves this function: the CA is reported by fingerprint only,
  * and the token is never read.
  */
-export declare function frpIngressSelfCheck(settings: FrpSettings, stateFile: string): Promise<FrpIngressSelfCheck>;
+export declare function frpIngressSelfCheck(settings: FrpSettings, stateFile: string, ownedRoot?: string): Promise<FrpIngressSelfCheck>;
 //#endregion
 //#region src/managed-setup.d.ts
 /** One host a server leaf must be valid for: an IP literal, a DNS name, or both. */
@@ -1423,7 +1612,12 @@ interface RemoteProviderStatus {
 }
 /** Lifecycle shared by selectable remote providers. */
 interface RemoteProviderController {
-  initialize(): Promise<void>;
+  /**
+   * Initialize from the current startup preparation, without retaining a permission-success cache.
+   * @param initialState - Fresh state prepared by this controller's own store; omission reads that store.
+   * @returns Completion of the normal provider initialization and optional startup.
+   */
+  initialize(initialState?: MobileAccessControlState): Promise<void>;
   gateway(): MobileAccessGateway | undefined;
   status(): RemoteProviderStatus;
   setEnabled(enabled: boolean): Promise<RemoteProviderStatus>;
@@ -1531,7 +1725,7 @@ export declare class FrpController implements RemoteProviderController {
   private ingressCertificateTimer;
   constructor(options: FrpControllerOptions);
   /** Restore the remembered FRP switch without changing LAN or other providers. */
-  initialize(): Promise<void>;
+  initialize(initialState?: MobileAccessControlState): Promise<void>;
   /** Return the active FRP-backed DSH gateway. */
   gateway(): MobileAccessGateway | undefined;
   /** Return state safe for the desktop control UI. */
@@ -1599,11 +1793,12 @@ export declare function validateOriginAllowedCidrs(value: unknown, listenHost: s
 export declare function parseOriginSettings(value: unknown): OriginSettings;
 /** Owns only origin settings; shared paired-device storage is never removed. */
 export declare class OriginConfigStore {
+  private readonly ownedRoot;
   readonly stateRoot: string;
   readonly settingsFile: string;
   private settingsValue;
   private errorCode;
-  constructor(stateDirectory: string);
+  constructor(stateDirectory: string, ownedRoot?: string);
   initialize(): Promise<void>;
   status(): OriginConfigurationStatus;
   settings(): OriginSettings | undefined;
@@ -1724,6 +1919,7 @@ export declare class CloudflaredComponentManager {
   readonly stateRoot: string;
   readonly logRoot: string;
   private readonly stagingRoot;
+  private readonly stateDirectory;
   private readonly platform;
   private readonly arch;
   private readonly release;
@@ -1803,11 +1999,12 @@ export declare function parseCloudflaredTunnelSettings(value: unknown): Cloudfla
 export declare function mergeSavedCloudflaredTunnelSettings(partial: Readonly<Record<string, unknown>>, saved: CloudflaredTunnelSettings | undefined): CloudflaredTunnelSettings;
 /** Owns the private cloudflared tunnel configuration for one DSH installation. */
 export declare class CloudflaredTunnelStore {
+  private readonly ownedRoot;
   readonly stateRoot: string;
   readonly settingsFile: string;
   private settingsValue;
   private errorCode;
-  constructor(stateDirectory: string);
+  constructor(stateDirectory: string, ownedRoot?: string);
   /** Load private settings while rejecting links, oversized files and unknown fields. */
   initialize(): Promise<void>;
   /** Return configuration metadata without exposing the connector token. */
@@ -1893,7 +2090,7 @@ export declare class CloudflaredController implements RemoteProviderController {
   private startupRounds;
   constructor(options: CloudflaredControllerOptions);
   /** Restore the remembered cloudflared switch independently from LAN and other providers. */
-  initialize(): Promise<void>;
+  initialize(initialState?: MobileAccessControlState): Promise<void>;
   /** Return the active cloudflared-backed DSH gateway. */
   gateway(): MobileAccessGateway | undefined;
   /** Return state safe for the desktop control UI. */
@@ -2009,5 +2206,5 @@ export declare function originGatewayConfig(template: ResolvedGatewayConfig, set
 /** Mount the resident control route and its optional authenticated LAN gateway. */
 export declare function apply(ctx: Context, config: PluginConfig): Promise<void>;
 //#endregion
-export { type AccessControllerOptions, type AuthoritySpec, type BlockedUpgradePathEntry, type CaddySiteOptions, type CertRenewalStatus, type ClientModuleEntry, type ClientModulePreferenceSelection, type ClientModulePreferenceView, type CloudflaredComponentStatus, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, type FrpComponentStatus, type FrpConfigurationStatus, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, type LocalExtensionManifest, type MobileAccessControlState, type MobileAccessControlStore, type MobileAccessService as MobileAccessRegistry, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, type OriginConfigurationStatus, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, type ResolvedGatewayConfig, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, type TaskCompletionEvent, type TaskEventContext, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig };
+export { type AccessControllerOptions, type AuthoritySpec, type BlockedUpgradePathEntry, type CaddySiteOptions, type CertRenewalStatus, type ClientModuleEntry, type ClientModulePreferenceSelection, type ClientModulePreferenceView, type CloudflaredComponentStatus, type CloudflaredControllerOptions, type CloudflaredState, type CloudflaredStatus, type CloudflaredTunnelMode, type CloudflaredTunnelSettings, type CloudflaredTunnelStatus, FRP_VHOST_HTTP_PORT as DEFAULT_VHOST_HTTP_PORT, type DeviceProbeResult, type DeviceSnapshot, type DeviceStore, type DeviceSummary, type DisabledTlsConfig, type FrpAttachOptions, type FrpAttachPlan, type FrpAttachPlanLocal, type FrpAttachPlanStep, type FrpAttachStepId, type FrpAttachTemplate, type FrpAttachVpsParts, type FrpComponentStatus, type FrpConfigurationStatus, type FrpControllerOptions, type FrpEntryTls, type FrpIngressCertificate, type FrpIngressPaths, type FrpIngressSelfCheck, type FrpSettings, type FrpState, type FrpStatus, type HostExecutionConfig, type LocalExtensionManifest, type MobileAccessControlState, type MobileAccessControlStore, type MobileAccessService as MobileAccessRegistry, type MobileAccessRuntime, type MobileActionContext, type MobileExtensionClientEntry, type MobileExtensionDefinition, type MobileExtensionManifest, type MobileExtensionStatus, type MobileHostAction, type MobileHostRoute, type MobileRouteRequest, type MobileRouteResponse, type MobileWorkerHostApi, type OriginConfigurationStatus, type OriginControllerOptions, type OriginSettings, type OriginState, type OriginStatus, type PairingResult, type ParsedCidr, type PluginConfig, type ProvidedTlsConfig, type RemoteProvider, type RemoteProviderController, type RemoteProviderState, type RemoteProviderStatus, type RenewalResult, type ResolvedGatewayConfig, type ResolvedHostExecutionConfig, type ServerCertificateAuthority, type ServerCertificateFiles, type ServerCertificateTarget, type SessionAuthorization, type SessionEndReason, type StoredDevice, type TaskCompletionEvent, type TaskEventContext, type TaskEventSession, type TaskEventSink, type TaskEventWatcherOptions, type TaskTurnEvent, type TlsConfig };
 //# sourceMappingURL=index.d.mts.map