@codesoul-co/hypha-core / contracts/remote-sandbox-provider
模块用法
用于声明并运行时校验契约。Remote sandbox provider 模块公开 10 接口、1 类型。
从包入口导入
ts
import type {
RemoteArtifactChunk,
RemoteArtifactChunkSequenceExpectation,
RemoteArtifactDownloadRequest,
RemoteArtifactTransferReceipt,
RemoteArtifactUploadRequest,
RemoteExecutionReconciliationRequest,
RemoteExecutionReconciliationResult,
RemoteOutputStreamRequest,
} from '@codesoul-co/hypha-core';
// 完整导出列表见下方。使用要点
- 11 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用
import type，运行时不应依赖它们。
公共导出
| Symbol | 种类 | 签名 | 说明 |
|---|---|---|---|
RemoteArtifactChunk | 接口 | interface RemoteArtifactChunk | Remote Artifact Chunk 接口，共包含 9 个公开字段或方法。 |
RemoteArtifactChunkSequenceExpectation | 接口 | interface RemoteArtifactChunkSequenceExpectation | Remote Artifact Chunk Sequence Expectation 接口，共包含 3 个公开字段或方法。 |
RemoteArtifactDownloadRequest | 接口 | interface RemoteArtifactDownloadRequest | Remote Artifact Download Request 接口，共包含 9 个公开字段或方法。 |
RemoteArtifactTransferReceipt | 接口 | interface RemoteArtifactTransferReceipt | Remote Artifact Transfer Receipt 接口，共包含 12 个公开字段或方法。 |
RemoteArtifactUploadRequest | 接口 | interface RemoteArtifactUploadRequest | Remote Artifact Upload Request 接口，共包含 12 个公开字段或方法。 |
RemoteExecutionReconciliationRequest | 接口 | interface RemoteExecutionReconciliationRequest | Remote Execution Reconciliation Request 接口，共包含 8 个公开字段或方法。 |
RemoteExecutionReconciliationResult | 接口 | interface RemoteExecutionReconciliationResult | Remote Execution Reconciliation Result 接口，共包含 8 个公开字段或方法。 |
RemoteOutputStreamRequest | 接口 | interface RemoteOutputStreamRequest | Remote Output Stream Request 接口，共包含 8 个公开字段或方法。 |
RemoteSandboxProvider | 接口 | interface RemoteSandboxProvider extends SandboxProvider | Remote Sandbox Provider 接口，共包含 15 个公开字段或方法。 |
RemoteSandboxProviderCapabilities | 接口 | interface RemoteSandboxProviderCapabilities extends SandboxProviderCapabilities | Remote Sandbox Provider Capabilities 接口，共包含 12 个公开字段或方法。 |
RemoteExecutionReconciliationState | 类型 | type RemoteExecutionReconciliationState = 'not_found' | 'accepted' | 'running' | 'completed' | 'failed' | 'cancelled' | 'unknown' | Remote Execution Reconciliation State 公共类型别名；完整类型表达式见声明。 |
RemoteArtifactChunk
Remote Artifact Chunk 接口，共包含 9 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteArtifactChunk } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteArtifactChunk {
transferId: string;
artifactRef: string;
sequence: number;
offsetBytes: number;
encoding: 'base64';
content: string;
byteLength: number;
contentHash: string;
final: boolean;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifactRef | 属性 | artifactRef: string | 公开属性；类型、只读和可选状态以签名列为准。 |
byteLength | 属性 | byteLength: number | 公开属性；类型、只读和可选状态以签名列为准。 |
content | 属性 | content: string | 公开属性；类型、只读和可选状态以签名列为准。 |
contentHash | 属性 | contentHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
encoding | 属性 | encoding: "base64" | 公开属性；类型、只读和可选状态以签名列为准。 |
final | 属性 | final: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
offsetBytes | 属性 | offsetBytes: number | 公开属性；类型、只读和可选状态以签名列为准。 |
sequence | 属性 | sequence: number | 公开属性；类型、只读和可选状态以签名列为准。 |
transferId | 属性 | transferId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteArtifactChunkSequenceExpectation
Remote Artifact Chunk Sequence Expectation 接口，共包含 3 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteArtifactChunkSequenceExpectation } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteArtifactChunkSequenceExpectation {
transferId: string;
artifactRef: string;
sizeBytes: number;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifactRef | 属性 | artifactRef: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sizeBytes | 属性 | sizeBytes: number | 公开属性；类型、只读和可选状态以签名列为准。 |
transferId | 属性 | transferId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteArtifactDownloadRequest
Remote Artifact Download Request 接口，共包含 9 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteArtifactDownloadRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteArtifactDownloadRequest {
operationId: string;
sandboxId: string;
principal: ExecutionPrincipal;
artifactRef: string;
maxBytes: number;
expectedContentHash?: string;
correlationId?: string;
causationId?: string;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifactRef | 属性 | artifactRef: string | 公开属性；类型、只读和可选状态以签名列为准。 |
causationId | 属性 | causationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
correlationId | 属性 | correlationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
expectedContentHash | 属性 | expectedContentHash?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
maxBytes | 属性 | maxBytes: number | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
operationId | 属性 | operationId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principal | 属性 | principal: ExecutionPrincipal | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteArtifactTransferReceipt
Remote Artifact Transfer Receipt 接口，共包含 12 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteArtifactTransferReceipt } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteArtifactTransferReceipt {
id: string;
providerId: string;
sandboxId: string;
artifactRef: string;
direction: 'upload' | 'download';
status: 'accepted' | 'completed' | 'rejected' | 'unknown';
sizeBytes: number;
contentHash?: string;
providerTransferRef?: string;
issuedAt: string;
receiptHash: string;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifactRef | 属性 | artifactRef: string | 公开属性；类型、只读和可选状态以签名列为准。 |
contentHash | 属性 | contentHash?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
direction | 属性 | direction: "upload" | "download" | 公开属性；类型、只读和可选状态以签名列为准。 |
id | 属性 | id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
issuedAt | 属性 | issuedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
providerId | 属性 | providerId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
providerTransferRef | 属性 | providerTransferRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
receiptHash | 属性 | receiptHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sizeBytes | 属性 | sizeBytes: number | 公开属性；类型、只读和可选状态以签名列为准。 |
status | 属性 | status: "unknown" | "accepted" | "completed" | "rejected" | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteArtifactUploadRequest
Remote Artifact Upload Request 接口，共包含 12 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteArtifactUploadRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteArtifactUploadRequest {
operationId: string;
sandboxId: string;
principal: ExecutionPrincipal;
expectedSandboxRevision: number;
artifactRef: string;
sizeBytes: number;
contentHash: string;
mediaType?: string;
idempotencyKey: string;
correlationId?: string;
causationId?: string;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
artifactRef | 属性 | artifactRef: string | 公开属性；类型、只读和可选状态以签名列为准。 |
causationId | 属性 | causationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
contentHash | 属性 | contentHash: string | 公开属性；类型、只读和可选状态以签名列为准。 |
correlationId | 属性 | correlationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
expectedSandboxRevision | 属性 | expectedSandboxRevision: number | 公开属性；类型、只读和可选状态以签名列为准。 |
idempotencyKey | 属性 | idempotencyKey: string | 公开属性；类型、只读和可选状态以签名列为准。 |
mediaType | 属性 | mediaType?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
operationId | 属性 | operationId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principal | 属性 | principal: ExecutionPrincipal | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sizeBytes | 属性 | sizeBytes: number | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteExecutionReconciliationRequest
Remote Execution Reconciliation Request 接口，共包含 8 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteExecutionReconciliationRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteExecutionReconciliationRequest {
operationId: string;
executionId: string;
sandboxId: string;
principal: ExecutionPrincipal;
providerExecutionRef?: string;
idempotencyKey?: string;
correlationId?: string;
causationId?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
causationId | 属性 | causationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
correlationId | 属性 | correlationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
idempotencyKey | 属性 | idempotencyKey?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
operationId | 属性 | operationId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principal | 属性 | principal: ExecutionPrincipal | 公开属性；类型、只读和可选状态以签名列为准。 |
providerExecutionRef | 属性 | providerExecutionRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteExecutionReconciliationResult
Remote Execution Reconciliation Result 接口，共包含 8 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteExecutionReconciliationResult } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteExecutionReconciliationResult {
executionId: string;
sandboxId: string;
state: RemoteExecutionReconciliationState;
providerExecutionRef?: string;
observedAt: string;
result?: CommandExecutionResult;
receipt?: ExecutionReceipt;
metadata?: Record<string, unknown>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
metadata | 属性 | metadata?: Record<string, unknown> | 公开属性；类型、只读和可选状态以签名列为准。 |
observedAt | 属性 | observedAt: string | 公开属性；类型、只读和可选状态以签名列为准。 |
providerExecutionRef | 属性 | providerExecutionRef?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
receipt | 属性 | receipt?: ExecutionReceipt | 公开属性；类型、只读和可选状态以签名列为准。 |
result | 属性 | result?: CommandExecutionResult | 公开属性；类型、只读和可选状态以签名列为准。 |
sandboxId | 属性 | sandboxId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
state | 属性 | state: RemoteExecutionReconciliationState | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteOutputStreamRequest
Remote Output Stream Request 接口，共包含 8 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteOutputStreamRequest } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteOutputStreamRequest {
operationId: string;
executionId: string;
principal: ExecutionPrincipal;
fromSequence?: number;
maxChunks?: number;
follow?: boolean;
correlationId?: string;
causationId?: string;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
causationId | 属性 | causationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
correlationId | 属性 | correlationId?: string | 公开属性；类型、只读和可选状态以签名列为准。 |
executionId | 属性 | executionId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
follow | 属性 | follow?: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
fromSequence | 属性 | fromSequence?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
maxChunks | 属性 | maxChunks?: number | 公开属性；类型、只读和可选状态以签名列为准。 |
operationId | 属性 | operationId: string | 公开属性；类型、只读和可选状态以签名列为准。 |
principal | 属性 | principal: ExecutionPrincipal | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteSandboxProvider
Remote Sandbox Provider 接口，共包含 15 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteSandboxProvider } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteSandboxProvider extends SandboxProvider {
capabilities(): Promise<RemoteSandboxProviderCapabilities>;
reconcileExecution(request: RemoteExecutionReconciliationRequest): Promise<RemoteExecutionReconciliationResult>;
streamOutput(request: RemoteOutputStreamRequest): AsyncIterable<CommandOutputChunk>;
uploadArtifact(request: RemoteArtifactUploadRequest, chunks: AsyncIterable<RemoteArtifactChunk>): Promise<RemoteArtifactTransferReceipt>;
downloadArtifact(request: RemoteArtifactDownloadRequest): AsyncIterable<RemoteArtifactChunk>;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
cancel | 方法 | cancel(request: ExecutionCancelRequest): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
capabilities | 方法 | capabilities(): Promise<RemoteSandboxProviderCapabilities> | 公开方法；参数与返回类型以签名列为准。 |
cleanup | 方法 | cleanup(request: SandboxCleanupRequest): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
close | 方法 | close?(): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
create | 方法 | create(request: SandboxCreateRequest): Promise<SandboxRecord> | 公开方法；参数与返回类型以签名列为准。 |
downloadArtifact | 方法 | downloadArtifact(request: RemoteArtifactDownloadRequest): AsyncIterable<RemoteArtifactChunk> | 公开方法；参数与返回类型以签名列为准。 |
execute | 方法 | execute(request: CommandExecutionRequest): Promise<CommandExecutionResult> | 公开方法；参数与返回类型以签名列为准。 |
health | 方法 | health(): Promise<ProviderHealth> | 公开方法；参数与返回类型以签名列为准。 |
id | 属性 | readonly id: string | 公开属性；类型、只读和可选状态以签名列为准。 |
reconcileExecution | 方法 | reconcileExecution(request: RemoteExecutionReconciliationRequest): Promise<RemoteExecutionReconciliationResult> | 公开方法；参数与返回类型以签名列为准。 |
start | 方法 | start(request: SandboxStartRequest): Promise<SandboxRecord> | 公开方法；参数与返回类型以签名列为准。 |
status | 方法 | status(request: SandboxStatusRequest): Promise<SandboxRecord | null> | 公开方法；参数与返回类型以签名列为准。 |
streamOutput | 方法 | streamOutput(request: RemoteOutputStreamRequest): AsyncIterable<CommandOutputChunk> | 公开方法；参数与返回类型以签名列为准。 |
terminate | 方法 | terminate(request: SandboxTerminateRequest): Promise<void> | 公开方法；参数与返回类型以签名列为准。 |
uploadArtifact | 方法 | uploadArtifact(request: RemoteArtifactUploadRequest, chunks: AsyncIterable<RemoteArtifactChunk>): Promise<RemoteArtifactTransferReceipt> | 公开方法；参数与返回类型以签名列为准。 |
RemoteSandboxProviderCapabilities
Remote Sandbox Provider Capabilities 接口，共包含 12 个公开字段或方法。
- 种类: 接口
- 导入:
import type { RemoteSandboxProviderCapabilities } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export interface RemoteSandboxProviderCapabilities extends SandboxProviderCapabilities {
remoteExecution: true;
}契约成员
| 成员 | 种类 | 签名 | 说明 |
|---|---|---|---|
cancellation | 属性 | cancellation: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
cpuLimits | 属性 | cpuLimits: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
diskLimits | 属性 | diskLimits: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
filesystemIsolation | 属性 | filesystemIsolation: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
imageDigestPinning | 属性 | imageDigestPinning: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
memoryLimits | 属性 | memoryLimits: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
networkIsolation | 属性 | networkIsolation: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
pidsLimit | 属性 | pidsLimit: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
processIsolation | 属性 | processIsolation: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
processTreeKill | 属性 | processTreeKill: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
remoteExecution | 属性 | remoteExecution: true | 公开属性；类型、只读和可选状态以签名列为准。 |
snapshots | 属性 | snapshots: boolean | 公开属性；类型、只读和可选状态以签名列为准。 |
RemoteExecutionReconciliationState
Remote Execution Reconciliation State 公共类型别名；完整类型表达式见声明。
- 种类: 类型
- 导入:
import type { RemoteExecutionReconciliationState } from '@codesoul-co/hypha-core'; - 源码模块:
contracts/remote-sandbox-provider
声明
text
export type RemoteExecutionReconciliationState = 'not_found' | 'accepted' | 'running' | 'completed' | 'failed' | 'cancelled' | 'unknown';