toolwire

package
v0.26.0 Latest Latest
Warning

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

 Go to latest Published: Oct 13, 2026 License: GPL-3.0 Imports: 10 Imported by: 0

Documentation

Overview

Package toolwire holds the messages of adapter protocol v1: newline- delimited JSON between the runtime and a tool process, over the tool's stdin and stdout, one task per process (docs/rfcs/sensor-sdk-v2.md, D.4.2). Both sides (pkg/tool/adapter, pkg/sensorkit/toolhost) use these types; the protocol's JSON Schema is in pkg/tool/schema.

Index

Constants

View Source 
const (
	TypeHello    = "hello"
	TypeDescribe = "describe"
	TypeValidate = "validate"
	TypeRun      = "run"
	TypeCancel   = "cancel"
)

Message types, runtime to adapter.

View Source 
const (
	TypeManifest     = "manifest"
	TypeValidation   = "validation"
	TypeLog          = "log"
	TypeProgress     = "progress"
	TypeRecord       = "record"
	TypeReportInfo   = "report_info"
	TypeTargetStatus = "target_status"
	TypeArtifact     = "artifact"
	TypeHeartbeat    = "heartbeat"
	TypeVerdict      = "verdict"
	TypeResult       = "result"
)

Message types, adapter to runtime (besides hello).

View Source 
const MaxLine = 1 << 20

MaxLine bounds one message.

View Source 
const Version = 1

Version is the protocol version.

Variables

View Source 
var ErrLineTooLong = errors.New("message larger than the protocol's line limit")

ErrLineTooLong is the error of a message larger than MaxLine.

View Source 
var Features = []string{"artifacts", "progress", "credentials", "target_status", "report_info", "retest"}

Features the runtime offers in its hello.

Functions

func Decode 

func Decode(line []byte, msg any) error

Decode decodes a line into msg. Members msg does not know are ignored (a newer peer may add some); records' data is decoded strictly where it is checked.

Types

type Artifact 

type Artifact struct {
	Envelope
	Name      string `json:"name"`
	MediaType string `json:"media_type"`
	// Path is relative to the task's directory.
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Size   int64  `json:"size"`
}

Artifact announces an artifact file in the task's directory.

type Cancel 

type Cancel struct {
	Envelope
	Reason string `json:"reason,omitempty"`
}

Cancel asks the adapter to stop.

type Credential 

type Credential struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

Credential is a credential delivered with a run: only those the manifest declares and the operator stored.

type Envelope 

type Envelope struct {
	V    int    `json:"v"`
	Type string `json:"type"`
}

Envelope is the part every message has.

func Env 

func Env(t string) Envelope

Env is an Envelope of type t.

func Peek 

func Peek(line []byte) (Envelope, error)

Peek decodes the envelope of a line.

type Error 

type Error struct {
	Class        tool.ErrorClass `json:"class"`
	Retryable    bool            `json:"retryable,omitempty"`
	RetryAfterMs int64           `json:"retry_after_ms,omitempty"`
	Detail       string          `json:"detail,omitempty"`
}

Error is a categorized error on the wire.

func FromError 

func FromError(e *tool.Error) *Error

FromError converts a tool error for the wire (detail capped).

func (*Error) ToError 

func (e *Error) ToError() *tool.Error

ToError converts a wire error. A class a tool may not claim becomes tool_error.

type Hello 

type Hello struct {
	Envelope
	Protocol []int       `json:"protocol"`
	Runtime  RuntimeInfo `json:"runtime"`
	Limits   Limits      `json:"limits"`
	Features []string    `json:"features,omitempty"`
}

Hello is the runtime's first message.

type HelloReply 

type HelloReply struct {
	Envelope
	Protocol int      `json:"protocol"`
	SDK      SDKInfo  `json:"sdk"`
	Features []string `json:"features,omitempty"`
}

HelloReply is the adapter's first message: the version it chose.

type Limits 

type Limits struct {
	MaxLine          int   `json:"max_line"`
	MaxRecords       int   `json:"max_records"`
	MaxOutputBytes   int64 `json:"max_output_bytes"`
	MaxArtifactBytes int64 `json:"max_artifact_bytes"`
}

Limits are the runtime's limits, announced in its hello.

type Log 

type Log struct {
	Envelope
	Level  string         `json:"level"`
	Msg    string         `json:"msg"`
	Fields map[string]any `json:"fields,omitempty"`
}

Log is a log line.

type ManifestMsg 

type ManifestMsg struct {
	Envelope
	Manifest json.RawMessage `json:"manifest"`
}

ManifestMsg answers describe.

type Progress 

type Progress struct {
	Envelope
	Done  int    `json:"done"`
	Total int    `json:"total"`
	Msg   string `json:"msg,omitempty"`
}

Progress reports progress.

type Reader 

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

Reader reads messages, refusing lines longer than MaxLine.

func NewReader 

func NewReader(r io.Reader) *Reader

NewReader reads from r.

func (*Reader) Next 

func (r *Reader) Next() ([]byte, error)

Next returns the next non-empty line (without its line ending). A line longer than MaxLine is ErrLineTooLong (the stream cannot be trusted after it).

type Record 

type Record struct {
	Envelope
	// Kind is asset, finding or dependency.
	Kind string `json:"kind"`
	// Target is the ref of the target the record belongs to ("" none).
	Target string          `json:"target,omitempty"`
	Data   json.RawMessage `json:"data"`
}

Record is one CTIS record.

type ReportInfoMsg 

type ReportInfoMsg struct {
	Envelope
	Info json.RawMessage `json:"info"`
}

ReportInfoMsg carries a report's tool, metadata and properties.

type Result 

type Result struct {
	Envelope
	Status tool.Status `json:"status"`
	Error  *Error      `json:"error,omitempty"`
	Stats  Stats       `json:"stats,omitzero"`
}

Result is the adapter's last message.

type Run 

type Run struct {
	Envelope
	Task RunTask `json:"task"`
}

Run starts the task.

type RunTask 

type RunTask struct {
	tool.Task
	// Workdir is the task's private directory.
	Workdir     string       `json:"workdir"`
	Credentials []Credential `json:"credentials,omitempty"`
}

RunTask is the task as the adapter receives it.

type RuntimeInfo 

type RuntimeInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
	OS      string `json:"os,omitempty"`
	Arch    string `json:"arch,omitempty"`
}

RuntimeInfo names the runtime.

type SDKInfo 

type SDKInfo struct {
	Name    string `json:"name"`
	Version string `json:"version,omitempty"`
}

SDKInfo names the adapter's SDK.

type Stats 

type Stats struct {
	Records int `json:"records,omitempty"`
}

Stats are the adapter's own counters (informational).

type TargetStatus 

type TargetStatus struct {
	Envelope
	Target string           `json:"target"`
	Status tool.TargetState `json:"status"`
	Error  *Error           `json:"error,omitempty"`
}

TargetStatus reports one target's outcome.

type Validate 

type Validate struct {
	Envelope
	Task tool.Task `json:"task"`
}

Validate asks the adapter to check a task.

type Validation 

type Validation struct {
	Envelope
	OK     bool              `json:"ok"`
	Errors []ValidationError `json:"errors,omitempty"`
}

Validation answers validate.

type ValidationError 

type ValidationError struct {
	Path    string `json:"path"`
	Message string `json:"message"`
}

ValidationError is one problem of a task.

type VerdictMsg 

type VerdictMsg struct {
	Envelope
	// Item is the ref of the retest item.
	Item    string       `json:"item"`
	Verdict tool.Verdict `json:"verdict"`
	Detail  string       `json:"detail,omitempty"`
	// Evidence and TemplateDigest support the verdict
	// (tool.VerdictReport); the runtime checks them again.
	Evidence       []ctis.EvidenceItem `json:"evidence,omitempty"`
	TemplateDigest string              `json:"template_digest,omitempty"`
}

VerdictMsg is a retest verdict on one item.

type Writer 

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

Writer writes messages, one per line, safely from several goroutines.

func NewWriter 

func NewWriter(w io.Writer) *Writer

NewWriter writes to w.

func (*Writer) Write 

func (w *Writer) Write(msg any) error

Write encodes msg (which must embed an Envelope with V and Type set) and flushes it.

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.