protocol

package
v0.6.0-rc.3 Latest Latest
Warning

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

 Go to latest Published: Aug 30, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package protocol defines the JSON protocol exchanged by connector binaries and Airlock. It has no platform or Agents SDK runtime dependencies.

Index

Constants

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
	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 ValidateContractID 

func ValidateContractID(id string) 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 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 DeviceCodeRequest 

type DeviceCodeRequest struct {
	Manifest Manifest `json:"manifest"`
}

type DeviceCodeResponse 

type DeviceCodeResponse struct {
	DeviceSecret        string    `json:"deviceSecret"`
	UserCode            string    `json:"userCode"`
	VerificationURL     string    `json:"verificationUrl"`
	ExpiresAt           time.Time `json:"expiresAt"`
	PollIntervalSeconds int       `json:"pollIntervalSeconds"`
	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 EnrollmentRequest 

type EnrollmentRequest struct {
	DeviceSecret string `json:"deviceSecret"`
}

type EnrollmentResponse 

type EnrollmentResponse struct {
	Status         string   `json:"status"`
	InstallationID string   `json:"installationId,omitempty"`
	Credential     string   `json:"credential,omitempty"`
	StorageOrigins []string `json:"storageOrigins,omitempty"`
	Error          string   `json:"error,omitempty"`
}

type Handshake 

type Handshake struct {
	ProtocolMajor int      `json:"protocolMajor"`
	ProtocolMinor int      `json:"protocolMinor"`
	Features      []string `json:"features"`
}

type HeartbeatRequest 

type HeartbeatRequest struct {
	Handshake       Handshake       `json:"handshake"`
	Readiness       Readiness       `json:"readiness"`
	ArtifactVersion string          `json:"artifactVersion"`
	ArtifactDigest  string          `json:"artifactDigest"`
	InterfaceHash   string          `json:"interfaceHash"`
	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"`
	ServiceMode    string              `json:"serviceMode"`
	Interface      Interface           `json:"interface"`
	InterfaceHash  string              `json:"interfaceHash"`
	ArtifactDigest string              `json:"artifactDigest"`
	Settings       []SettingDescriptor `json:"settings"`
}

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 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"`
	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 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.

func (Target) SupportsServiceMode 

func (t Target) SupportsServiceMode(mode string) bool

SupportsServiceMode reports whether target has a managed-service lifecycle for mode.

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.