@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/environment/ports.d.ts

@@ -0,0 +1,182 @@
+import { type EntrypointKind } from '../entrypoint-kinds.js';
+import { EntrypointDerivative } from '../schema.js';
+import { type HolderProcess } from './claims.js';
+import { type EnvironmentDiagnostic, type EnvironmentObservation, type HolderId, type Observation, type StackId } from './contract.js';
+import { type StateNamespace } from './state.js';
+export declare function observePortFamily(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly observedAt: string;
+    readonly leaseEvidence?: LeasePortFamilyResult;
+}): Promise<EnvironmentObservation>;
+export interface PortFamilyConfig {
+    readonly step: number;
+    readonly count: number;
+    readonly bases: Readonly<Record<string, number>>;
+}
+export interface PortListenerEvidenceInput {
+    readonly ports: readonly number[];
+    readonly observation: Observation<readonly number[]>;
+}
+export type PortListenerHost = '127.0.0.1' | '::1' | '0.0.0.0' | '::';
+export interface PortListenerBinding {
+    readonly hostIp: PortListenerHost;
+    readonly port: number;
+    readonly expected: 'listening' | 'free';
+}
+export type PortListenerObservation = Readonly<{
+    kind: 'complete';
+    rows: readonly Readonly<{
+        hostIp: PortListenerHost;
+        probeHost: '127.0.0.1' | '::1';
+        port: number;
+        listening: boolean;
+    }>[];
+    observedAt: string;
+}> | Readonly<{
+    kind: 'unavailable';
+    reason: string;
+}>;
+export interface PortLease {
+    readonly stackId: StackId;
+    readonly offset: number;
+    readonly ports: Readonly<Record<string, number>>;
+}
+type PortRefusal = {
+    readonly kind: 'refusal';
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+};
+export type LeasePortFamilyResult = {
+    readonly kind: 'complete';
+    readonly change: 'acquired' | 'unchanged';
+    readonly holderId: HolderId;
+    readonly recordRevision: number;
+    readonly lease: PortLease;
+    readonly observation: 'resolved-listener-evidence-accepted';
+} | PortRefusal;
+export type ReleasePortFamilyResult = {
+    readonly kind: 'complete';
+    readonly change: 'released' | 'retained' | 'unchanged';
+} | PortRefusal;
+export interface DerivedEntrypoint {
+    readonly name: string;
+    readonly kind: EntrypointKind;
+    readonly port: string;
+    readonly value: string;
+}
+export type DeriveEntrypointsResult = {
+    readonly kind: 'complete';
+    readonly values: readonly DerivedEntrypoint[];
+    readonly diagnostics: readonly EnvironmentDiagnostic[];
+} | PortRefusal;
+export interface PortLeaseProjection {
+    readonly lease: PortLease;
+    readonly ownership: Readonly<{
+        change: 'acquired' | 'unchanged';
+        holderId: HolderId;
+        recordRevision: number;
+        holderCount: number;
+        holderIds: readonly HolderId[];
+    }>;
+    readonly entrypoints: readonly DerivedEntrypoint[];
+}
+export declare function projectPortLeaseResult(input: {
+    readonly leaseResult: LeasePortFamilyResult;
+    readonly entrypointResult: DeriveEntrypointsResult;
+}): PortLeaseProjection | undefined;
+export type RetainedPortFamilyResult = Readonly<{
+    readonly kind: 'complete';
+    readonly holderId: HolderId;
+    readonly recordRevision: number;
+    readonly lease: PortLease;
+}> | PortRefusal;
+export declare function observeRetainedPortFamily(supplied: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly checkoutId: import('./contract.js').CheckoutId;
+    readonly config: PortFamilyConfig | 'recorded';
+}): Promise<RetainedPortFamilyResult>;
+export declare function inspectRecordedPortDeclaration(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly config: PortFamilyConfig;
+}): Promise<Readonly<{
+    kind: 'complete';
+    changed: boolean;
+}> | PortRefusal>;
+export declare function projectRetainedPortFamilyResult(input: {
+    readonly retainedResult: RetainedPortFamilyResult;
+    readonly entrypointResult: DeriveEntrypointsResult;
+}): Promise<PortLeaseProjection | undefined>;
+export declare function consumePortLeaseProjection(projection: PortLeaseProjection): PortLeaseProjection | undefined;
+export declare function inspectPortLeaseProjection(projection: PortLeaseProjection, namespace?: StateNamespace): PortLeaseProjection | undefined;
+export declare function revalidatePortLeaseProjection(input: {
+    readonly projection: PortLeaseProjection;
+    readonly namespace: StateNamespace;
+}): Promise<boolean>;
+export type PortLeaseTransferInspection = Readonly<{
+    readonly kind: 'complete';
+}> | PortRefusal;
+export declare function inspectPortLeaseTransfer(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly checkoutId: import('./contract.js').CheckoutId;
+    readonly previousHolderId: HolderId;
+    readonly projection: PortLeaseProjection;
+}): Promise<PortLeaseTransferInspection>;
+export declare function observePortListeners(input: {
+    readonly bindings: readonly PortListenerBinding[];
+    readonly timeoutMs: number;
+}): Promise<PortListenerObservation>;
+export declare function leasePortFamily(supplied: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly holderId: HolderId;
+    readonly checkoutId: import('./contract.js').CheckoutId;
+    readonly config: PortFamilyConfig;
+    readonly now: string;
+    readonly listenerTimeoutMs: number;
+    readonly listenerEvidence: readonly PortListenerEvidenceInput[];
+    readonly holderProcess?: HolderProcess;
+}): Promise<LeasePortFamilyResult>;
+export type CompensateAcquiredPortHolderResult = Readonly<{
+    readonly kind: 'complete';
+    readonly change: 'compensated';
+    readonly recordRevision: number;
+    readonly remainingHolderIds: readonly HolderId[];
+}> | PortRefusal;
+export declare function compensateAcquiredPortHolder(input: {
+    readonly namespace: StateNamespace;
+    readonly leaseResult: LeasePortFamilyResult;
+    readonly now: string;
+}): Promise<CompensateAcquiredPortHolderResult>;
+export type AcquirePortProjectionResult = Readonly<{
+    kind: 'complete';
+    leaseResult: LeasePortFamilyResult;
+    projection: PortLeaseProjection;
+}> | PortRefusal | Readonly<{
+    kind: 'unavailable';
+}>;
+/**
+ * Lease the port family and project its entrypoints as one step. A caller only ever receives a
+ * lease together with its projection, so when derivation or projection fails after this call added
+ * a holder, nobody downstream could release it: give exactly that holder back here.
+ */
+export declare function acquirePortProjection(input: Parameters<typeof leasePortFamily>[0] & {
+    readonly declarations: readonly EntrypointDerivative[];
+}): Promise<AcquirePortProjectionResult>;
+export declare function releasePortFamily(input: {
+    readonly namespace: StateNamespace;
+    readonly stackId: StackId;
+    readonly requesterId: HolderId;
+    readonly holderId: HolderId;
+    readonly now: string;
+}): Promise<ReleasePortFamilyResult>;
+export declare function deriveEntrypoints(input: {
+    readonly lease: PortLease | null;
+    readonly declarations: readonly EntrypointDerivative[];
+    readonly declaredValues?: Readonly<Record<string, string>>;
+}): DeriveEntrypointsResult;
+export {};