protocol

package
v0.6.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 6, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package protocol defines the JSON protocols exchanged by connector children, airlock-host, and Airlock. It has no platform or runtime dependencies.

Index

Constants

View Source 
const (
	HostProtocolVersion           = 1
	MaxChildFrameBytes            = 8 << 20
	MaxHostSyncBytes              = MaxChildFrameBytes
	MaxHostInventoryMutationBytes = 2*MaxManifestBytes + (64 << 10)
	MaxHostedConnectors           = 1000
	MaxHostedStatusErrorBytes     = 128
	MaxHostDisplayNameBytes       = 256
	MaxHostStorageOrigins         = 64
	MaxHostStorageOriginBytes     = 2048
)
View Source 
const (
	Major = 1
	Minor = 0

	// MaxEnvelopeBytes matches Airlock's connector protocol request limit.
	MaxEnvelopeBytes = 1 << 20
	// MaxJobPayloadBytes reserves enough room for the JSON completion envelope,
	// attempt token, status, and escaping under MaxEnvelopeBytes.
	MaxJobPayloadBytes      = MaxEnvelopeBytes - (64 << 10)
	MaxInlineFileBytes      = (MaxJobPayloadBytes * 3 / 4) - (16 << 10)
	MaxManifestBytes        = 4 << 20
	MaxInterfaceBytes       = 1 << 20
	MaxSettingsSchemaBytes  = 256 << 10
	MaxSchemaBytes          = 512 << 10
	MaxTransferPartBytes    = 16 << 20
	MaxTransferParts        = 10000
	MaxDirectoryScanEntries = 10000
	MaxActiveAttempts       = 256
)
View Source 
const (
	PlatformLinuxAMD64   = "linux-amd64"
	PlatformLinuxARM64   = "linux-arm64"
	PlatformLinuxARMv7   = "linux-armv7"
	PlatformDarwinAMD64  = "darwin-amd64"
	PlatformDarwinARM64  = "darwin-arm64"
	PlatformWindowsAMD64 = "windows-amd64"
	PlatformWindowsARM64 = "windows-arm64"
)

Variables

This section is empty.

Functions

func CanonicalJSON 

func CanonicalJSON(value []byte) ([]byte, error)

func HashJSON 

func HashJSON(value []byte) (string, error)

func InterfaceDigest 

func InterfaceDigest(value Interface) (string, error)

func ValidateArtifactDigest 

func ValidateArtifactDigest(value string) error

func ValidateChildEnvelope 

func ValidateChildEnvelope(envelope ChildEnvelope) error

func ValidateContractID 

func ValidateContractID(id string) error

func ValidateHostConnectorInventoryMutationRequest 

func ValidateHostConnectorInventoryMutationRequest(request HostConnectorInventoryMutationRequest) error

func ValidateHostConnectorInventoryMutationResponse 

func ValidateHostConnectorInventoryMutationResponse(response HostConnectorInventoryMutationResponse) error

func ValidateHostSyncRequest 

func ValidateHostSyncRequest(request HostSyncRequest) error

func ValidateHostedConnectorManifest 

func ValidateHostedConnectorManifest(manifest HostedConnectorManifest) error

func ValidateKind 

func ValidateKind(kind string) error

func ValidateManifest 

func ValidateManifest(m Manifest) error

func ValidateName 

func ValidateName(kind, name string) error

func ValidateRequirement 

func ValidateRequirement(r Requirement) error

func ValidateSettings 

func ValidateSettings(settings []SettingDescriptor) error

Types

type ActiveAttempt 

type ActiveAttempt struct {
	JobID        string `json:"jobId"`
	AttemptToken string `json:"attemptToken"`
}

type ChildCancel 

type ChildCancel struct {
	JobID        string `json:"jobId"`
	AttemptToken string `json:"attemptToken"`
}

type ChildDecoder 

type ChildDecoder struct {
	// contains filtered or unexported fields
}

ChildDecoder reads strict, length-prefixed child protocol frames.

func NewChildDecoder 

func NewChildDecoder(reader io.Reader) *ChildDecoder

func (*ChildDecoder) Decode 

func (d *ChildDecoder) Decode(envelope *ChildEnvelope) error

type ChildEncoder 

type ChildEncoder struct {
	// contains filtered or unexported fields
}

ChildEncoder writes concurrency-safe, length-prefixed child protocol frames.

func NewChildEncoder 

func NewChildEncoder(writer io.Writer) *ChildEncoder

func (*ChildEncoder) Encode 

func (e *ChildEncoder) Encode(envelope ChildEnvelope) error

type ChildEnvelope 

type ChildEnvelope struct {
	Type       ChildMessageType `json:"type"`
	Initialize *ChildInitialize `json:"initialize,omitempty"`
	Settings   *ChildSettings   `json:"settings,omitempty"`
	Ready      *ChildReady      `json:"ready,omitempty"`
	Job        *JobRequest      `json:"job,omitempty"`
	Cancel     *ChildCancel     `json:"cancel,omitempty"`
	Event      *JobEvent        `json:"event,omitempty"`
	Completion *JobCompletion   `json:"completion,omitempty"`
}

ChildEnvelope is the framed JSON protocol between airlock-host and one connector child. Exactly one payload matching Type must be present.

type ChildInitialize 

type ChildInitialize struct {
	ProtocolVersion int             `json:"protocolVersion"`
	InstallationID  string          `json:"installationId"`
	Settings        json.RawMessage `json:"settings"`
	StateDirectory  string          `json:"stateDirectory"`
	StorageOrigins  []string        `json:"storageOrigins,omitempty"`
}

type ChildMessageType 

type ChildMessageType string
const (
	ChildMessageInitialize ChildMessageType = "initialize"
	ChildMessageSettings   ChildMessageType = "settings"
	ChildMessageReady      ChildMessageType = "ready"
	ChildMessageJob        ChildMessageType = "job"
	ChildMessageCancel     ChildMessageType = "cancel"
	ChildMessageEvent      ChildMessageType = "event"
	ChildMessageCompletion ChildMessageType = "completion"
)

type ChildReady 

type ChildReady struct {
	ProtocolVersion int       `json:"protocolVersion"`
	Manifest        Manifest  `json:"manifest"`
	Readiness       Readiness `json:"readiness"`
	Error           string    `json:"error,omitempty"`
}

type ChildSettings 

type ChildSettings struct {
	Settings       json.RawMessage `json:"settings"`
	StorageOrigins []string        `json:"storageOrigins,omitempty"`
}

type CommandCallRequest 

type CommandCallRequest struct {
	RequestID        string          `json:"requestId,omitempty"`
	Revision         int             `json:"revision"`
	Mode             CommandMode     `json:"mode"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
	Input            json.RawMessage `json:"input"`
	Deadline         *time.Time      `json:"deadline,omitempty"`
}

type CommandCallResponse 

type CommandCallResponse struct {
	JobID  string          `json:"jobId"`
	Status string          `json:"status"`
	Output json.RawMessage `json:"output,omitempty"`
	Error  string          `json:"error,omitempty"`
}

type CommandDescriptor 

type CommandDescriptor struct {
	Name             string          `json:"name"`
	Revision         int             `json:"revision"`
	Description      string          `json:"description,omitempty"`
	Mode             CommandMode     `json:"mode"`
	InputSchema      json.RawMessage `json:"inputSchema"`
	OutputSchema     json.RawMessage `json:"outputSchema"`
	InputSchemaHash  string          `json:"inputSchemaHash"`
	OutputSchemaHash string          `json:"outputSchemaHash"`
}

type CommandMode 

type CommandMode string
const (
	CommandModeUnary CommandMode = "unary"
	CommandModeJob   CommandMode = "job"
)

type ConnectorArtifactInput 

type ConnectorArtifactInput struct {
	InstallationID string          `json:"installationId,omitempty"`
	URL            string          `json:"url"`
	Filename       string          `json:"filename"`
	SHA256         string          `json:"sha256"`
	SizeBytes      int64           `json:"sizeBytes"`
	Settings       json.RawMessage `json:"settings,omitempty"`
	StorageOrigins []string        `json:"storageOrigins,omitempty"`
}

type DirectoryDescriptor 

type DirectoryDescriptor struct {
	Name        string `json:"name"`
	Revision    int    `json:"revision"`
	Description string `json:"description,omitempty"`
	Read        bool   `json:"read"`
	Write       bool   `json:"write"`
	List        bool   `json:"list"`
}

type DirectoryEntry 

type DirectoryEntry struct {
	Path        string    `json:"path"`
	Name        string    `json:"name"`
	Size        int64     `json:"size"`
	Mode        uint32    `json:"mode"`
	Directory   bool      `json:"directory"`
	ContentType string    `json:"contentType,omitempty"`
	ModifiedAt  time.Time `json:"modifiedAt"`
}

type DirectoryExportRequest 

type DirectoryExportRequest struct {
	Path     string            `json:"path"`
	PartSize int64             `json:"partSize"`
	Parts    []UploadPartGrant `json:"parts"`
	Grant    TransferGrant     `json:"grant"`
}

type DirectoryExportResponse 

type DirectoryExportResponse struct {
	Parts  []UploadedPart `json:"parts"`
	Size   int64          `json:"size"`
	SHA256 string         `json:"sha256"`
}

type DirectoryImportRequest 

type DirectoryImportRequest struct {
	Path      string        `json:"path"`
	Overwrite bool          `json:"overwrite"`
	Grant     TransferGrant `json:"grant"`
}

type DirectoryListRequest 

type DirectoryListRequest struct {
	Path   string `json:"path"`
	Cursor string `json:"cursor,omitempty"`
	Limit  int    `json:"limit,omitempty"`
}

type DirectoryListResponse 

type DirectoryListResponse struct {
	Entries    []DirectoryEntry `json:"entries"`
	NextCursor string           `json:"nextCursor,omitempty"`
}

type DirectoryMoveRequest 

type DirectoryMoveRequest struct {
	From      string `json:"from"`
	To        string `json:"to"`
	Overwrite bool   `json:"overwrite"`
}

type DirectoryReadRequest 

type DirectoryReadRequest struct {
	Path   string `json:"path"`
	Offset int64  `json:"offset,omitempty"`
	Length int64  `json:"length,omitempty"`
}

type DirectoryReadResponse 

type DirectoryReadResponse struct {
	Entry DirectoryEntry `json:"entry"`
	Data  []byte         `json:"data"`
}

type DirectoryWriteRequest 

type DirectoryWriteRequest struct {
	Path      string `json:"path"`
	Data      []byte `json:"data"`
	Overwrite bool   `json:"overwrite"`
}

type HostConnectorInventoryMutationRequest 

type HostConnectorInventoryMutationRequest struct {
	InstallationID string                     `json:"installationId"`
	Revision       uint64                     `json:"revision"`
	Kind           HostConnectorMutationKind  `json:"kind"`
	DisplayName    string                     `json:"displayName,omitempty"`
	Active         *ObservedConnectorArtifact `json:"active,omitempty"`
	Rollback       *ObservedConnectorArtifact `json:"rollback,omitempty"`
}

HostConnectorInventoryMutationRequest is one durable, monotonic mutation for a physical connector installation. A remove mutation is a tombstone.

type HostConnectorInventoryMutationResponse 

type HostConnectorInventoryMutationResponse struct {
	InstallationID       string   `json:"installationId"`
	AcknowledgedRevision uint64   `json:"acknowledgedRevision"`
	StorageOrigins       []string `json:"storageOrigins,omitempty"`
}

HostConnectorInventoryMutationResponse acknowledges the durable revision and returns the storage origins Airlock authorizes for the active installation.

type HostConnectorMutationKind 

type HostConnectorMutationKind string
const (
	HostConnectorMutationUpsert HostConnectorMutationKind = "upsert"
	HostConnectorMutationRemove HostConnectorMutationKind = "remove"
)

type HostInfo 

type HostInfo struct {
	ProtocolVersion int              `json:"protocolVersion"`
	Name            string           `json:"name"`
	Platform        string           `json:"platform"`
	Architecture    string           `json:"architecture"`
	AccessMode      RemoteAccessMode `json:"accessMode"`
	Version         string           `json:"version"`
}

type HostManagementCompletion 

type HostManagementCompletion struct {
	JobID        string          `json:"jobId"`
	AttemptToken string          `json:"attemptToken"`
	Status       string          `json:"status"`
	Output       json.RawMessage `json:"output,omitempty"`
	Error        string          `json:"error,omitempty"`
}

type HostManagementEvent 

type HostManagementEvent struct {
	AttemptToken string    `json:"attemptToken"`
	Sequence     int64     `json:"sequence"`
	Phase        string    `json:"phase"`
	Message      string    `json:"message,omitempty"`
	Time         time.Time `json:"time"`
}

type HostManagementJob 

type HostManagementJob struct {
	JobID        string          `json:"jobId"`
	AttemptToken string          `json:"attemptToken"`
	Input        json.RawMessage `json:"input"`
	Deadline     time.Time       `json:"deadline"`
}

type HostPollRequest 

type HostPollRequest struct {
	ActiveManagementAttempts []ActiveAttempt `json:"activeManagementAttempts,omitempty"`
	ActiveConnectorAttempts  []ActiveAttempt `json:"activeConnectorAttempts,omitempty"`
}

type HostPollResponse 

type HostPollResponse struct {
	Work []HostWork `json:"work"`
}

type HostSyncRequest 

type HostSyncRequest struct {
	Host       HostInfo                `json:"host"`
	Connectors []HostedConnectorStatus `json:"connectors"`
}

type HostSyncResponse 

type HostSyncResponse struct {
	HostID           string `json:"hostId"`
	HeartbeatSeconds int    `json:"heartbeatSeconds"`
	LongPollSeconds  int    `json:"longPollSeconds"`
}

type HostWork 

type HostWork struct {
	Kind          HostWorkKind       `json:"kind"`
	ConnectorID   string             `json:"connectorId,omitempty"`
	ConnectorJob  *JobRequest        `json:"connectorJob,omitempty"`
	Cancel        *ChildCancel       `json:"cancel,omitempty"`
	ManagementJob *HostManagementJob `json:"managementJob,omitempty"`
}

type HostWorkKind 

type HostWorkKind string
const (
	HostWorkConnectorJob      HostWorkKind = "connector_job"
	HostWorkConnectorCancel   HostWorkKind = "connector_cancel"
	HostWorkShell             HostWorkKind = "shell"
	HostWorkConnectorInstall  HostWorkKind = "connector_install"
	HostWorkConnectorUpdate   HostWorkKind = "connector_update"
	HostWorkConnectorRemove   HostWorkKind = "connector_remove"
	HostWorkConnectorRollback HostWorkKind = "connector_rollback"
)

type HostedConnectorManifest 

type HostedConnectorManifest struct {
	ProtocolMajor   int      `json:"protocolMajor"`
	ProtocolMinor   int      `json:"protocolMinor"`
	Features        []string `json:"features"`
	ArtifactVersion string   `json:"artifactVersion"`
	ArtifactDigest  string   `json:"artifactDigest"`
	InterfaceHash   string   `json:"interfaceHash"`
}

func SummarizeManifest 

func SummarizeManifest(manifest Manifest) HostedConnectorManifest

type HostedConnectorStatus 

type HostedConnectorStatus struct {
	InstallationID string                  `json:"installationId"`
	Manifest       HostedConnectorManifest `json:"manifest"`
	Readiness      Readiness               `json:"readiness"`
	ActiveAttempts []ActiveAttempt         `json:"activeAttempts,omitempty"`
	Error          string                  `json:"error,omitempty"`
}

type Interface 

type Interface struct {
	Kind            string                `json:"kind"`
	ContractID      string                `json:"contractId"`
	Name            string                `json:"name"`
	Description     string                `json:"description"`
	ArtifactVersion string                `json:"artifactVersion"`
	Commands        []CommandDescriptor   `json:"commands"`
	Directories     []DirectoryDescriptor `json:"directories"`
}

type JobCompletion 

type JobCompletion struct {
	AttemptToken string          `json:"attemptToken"`
	Status       string          `json:"status"`
	Output       json.RawMessage `json:"output,omitempty"`
	Error        string          `json:"error,omitempty"`
}

type JobEvent 

type JobEvent struct {
	AttemptToken string    `json:"attemptToken"`
	Sequence     int64     `json:"sequence"`
	Phase        string    `json:"phase"`
	Message      string    `json:"message,omitempty"`
	Completed    int64     `json:"completed,omitempty"`
	Total        int64     `json:"total,omitempty"`
	Time         time.Time `json:"time"`
}

type JobKind 

type JobKind string
const (
	JobKindCommand         JobKind = "command"
	JobKindDirectoryList   JobKind = "directory_list"
	JobKindDirectoryStat   JobKind = "directory_stat"
	JobKindDirectoryRead   JobKind = "directory_read"
	JobKindDirectoryWrite  JobKind = "directory_write"
	JobKindDirectoryDelete JobKind = "directory_delete"
	JobKindDirectoryMove   JobKind = "directory_move"
	JobKindDirectoryImport JobKind = "directory_import"
	JobKindDirectoryExport JobKind = "directory_export"
	JobKindCancel          JobKind = "cancel"
)

type JobRequest 

type JobRequest struct {
	JobID            string          `json:"jobId"`
	AttemptToken     string          `json:"attemptToken"`
	IdempotencyID    string          `json:"idempotencyId"`
	Kind             JobKind         `json:"kind"`
	Operation        string          `json:"operation"`
	Revision         int             `json:"revision"`
	Mode             CommandMode     `json:"mode,omitempty"`
	InputSchemaHash  string          `json:"inputSchemaHash,omitempty"`
	OutputSchemaHash string          `json:"outputSchemaHash,omitempty"`
	Input            json.RawMessage `json:"input"`
	Deadline         time.Time       `json:"deadline"`
}

type Manifest 

type Manifest struct {
	ProtocolMajor  int                 `json:"protocolMajor"`
	ProtocolMinor  int                 `json:"protocolMinor"`
	Features       []string            `json:"features"`
	Targets        []string            `json:"targets"`
	Interface      Interface           `json:"interface"`
	InterfaceHash  string              `json:"interfaceHash"`
	ArtifactDigest string              `json:"artifactDigest"`
	Settings       []SettingDescriptor `json:"settings"`
}

type ObservedConnectorArtifact 

type ObservedConnectorArtifact struct {
	Manifest       Manifest `json:"manifest"`
	MeasuredDigest string   `json:"measuredDigest"`
}

ObservedConnectorArtifact binds a validated manifest to the digest measured from the executable bytes by airlock-host.

type OfflinePolicy 

type OfflinePolicy string
const (
	OfflineFail   OfflinePolicy = "fail"
	OfflineSkip   OfflinePolicy = "skip"
	OfflineWait   OfflinePolicy = "wait"
	OfflineCancel OfflinePolicy = "cancel"
)

type OrchestrationRequest 

type OrchestrationRequest struct {
	RequestID      string                `json:"requestId"`
	Targets        TargetSelector        `json:"targets"`
	Strategy       OrchestrationStrategy `json:"strategy"`
	OfflinePolicy  OfflinePolicy         `json:"offlinePolicy"`
	MaxConcurrency int                   `json:"maxConcurrency,omitempty"`
	BatchSize      int                   `json:"batchSize,omitempty"`
	CanaryCount    int                   `json:"canaryCount,omitempty"`
	Quorum         int                   `json:"quorum,omitempty"`
	Deadline       *time.Time            `json:"deadline,omitempty"`
	Command        CommandCallRequest    `json:"command"`
}

type OrchestrationStrategy 

type OrchestrationStrategy string
const (
	StrategyParallel OrchestrationStrategy = "parallel"
	StrategySerial   OrchestrationStrategy = "serial"
	StrategyRolling  OrchestrationStrategy = "rolling"
	StrategyCanary   OrchestrationStrategy = "canary"
	StrategyQuorum   OrchestrationStrategy = "quorum"
)

type Readiness 

type Readiness string
const (
	ReadinessOffline            Readiness = "offline"
	ReadinessStarting           Readiness = "starting"
	ReadinessNeedsConfiguration Readiness = "needs_configuration"
	ReadinessIncompatible       Readiness = "incompatible_protocol"
	ReadinessUnhealthy          Readiness = "unhealthy"
	ReadinessReady              Readiness = "ready"
)

type RemoteAccessMode 

type RemoteAccessMode string
const (
	RemoteAccessFull       RemoteAccessMode = "full"
	RemoteAccessUpdateOnly RemoteAccessMode = "update_only"
	RemoteAccessNone       RemoteAccessMode = "none"
)

type Requirement 

type Requirement struct {
	ContractID  string                `json:"contractId"`
	Commands    []CommandDescriptor   `json:"commands"`
	Directories []DirectoryDescriptor `json:"directories"`
}

type SettingDescriptor 

type SettingDescriptor struct {
	Name        string   `json:"name"`
	JSONName    string   `json:"jsonName,omitempty"`
	Kind        string   `json:"kind"`
	Description string   `json:"description,omitempty"`
	Required    bool     `json:"required,omitempty"`
	Default     string   `json:"default,omitempty"`
	Enum        []string `json:"enum,omitempty"`
}

type ShellInput 

type ShellInput struct {
	Command          string            `json:"command"`
	Arguments        []string          `json:"arguments,omitempty"`
	Environment      map[string]string `json:"environment,omitempty"`
	WorkingDirectory string            `json:"workingDirectory,omitempty"`
	Stdin            []byte            `json:"stdin,omitempty"`
	MaxOutputBytes   int64             `json:"maxOutputBytes,omitempty"`
}

type ShellOutput 

type ShellOutput struct {
	ExitCode int    `json:"exitCode"`
	Stdout   []byte `json:"stdout,omitempty"`
	Stderr   []byte `json:"stderr,omitempty"`
}

type Target 

type Target struct {
	ID               string
	Architecture     string
	GOOS             string
	GOARCH           string
	ExecutableSuffix string
	// contains filtered or unexported fields
}

Target defines one supported connector artifact platform and its Go build recipe. Connector manifests carry Target.ID values; builders own the recipe.

func LookupTarget 

func LookupTarget(id string) (Target, bool)

LookupTarget returns the registered build target for id.

func SupportedTargets 

func SupportedTargets() []Target

SupportedTargets returns every registered target in stable order.

func (Target) GoEnv 

func (t Target) GoEnv() []string

GoEnv returns a fresh Go environment fragment for cross-compiling the target.

type TargetSelector 

type TargetSelector struct {
	ResourceIDs []string          `json:"resourceIds,omitempty"`
	Labels      map[string]string `json:"labels,omitempty"`
}

type TransferGrant 

type TransferGrant struct {
	URL            string            `json:"url"`
	ExpiresAt      time.Time         `json:"expiresAt"`
	MaximumSize    int64             `json:"maximumSize"`
	ExpectedSize   int64             `json:"expectedSize,omitempty"`
	ExpectedSHA256 string            `json:"expectedSha256,omitempty"`
	Headers        map[string]string `json:"headers,omitempty"`
}

type UploadPartGrant 

type UploadPartGrant struct {
	Number int    `json:"number"`
	URL    string `json:"url"`
}

type UploadedPart 

type UploadedPart struct {
	Number int    `json:"number"`
	ETag   string `json:"etag"`
	Size   int64  `json:"size"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.