tap

package
v0.2.21 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 7 Imported by: 0

README

TAP Go SDK

This small standard-library-only client implements the JSON-line broker used by compiled WASI primitives. Client.Request(method, fields) supports tools, call, exec, read, write, and fetch; it creates a unique request ID, matches the reply, and returns the runner fields including result, stdout/stderr, command exit, HTTP status, refusal, violation/landed, unknown, and gated state. Client.Call(alias, arguments) is a typed convenience for connector calls and converts a nonzero call exit to a failed error. Client.Read(path) preserves empty-file success and converts a nonzero read exit into an error. Client.Return(stdout, stderr, exit) sends the final result frame.

Refusal, violation, unknown, malformed, and mismatched responses become typed *tap.Error values; unknown takes precedence over the refused message that accompanies an unknown outcome. Generic Request preserves command exit and HTTP status for the caller to interpret, including a nonzero write exit, so callers must check Reply.Exit before treating a write as successful. The SDK performs no filesystem, network, subprocess, or environment access itself. The Go language example includes a local copy of this source so it builds in isolation.

Documentation

Overview

Package tap provides the minimal JSON-line broker client for compiled Go primitives running as WASI Preview1 guests.

It deliberately exposes only the declared file-read operation and the runner's final return frame. It performs no filesystem or environment access itself beyond the supplied protocol streams.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Client

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

Client sends one request at a time and matches each answer by request ID.

func New

func New() *Client

New creates a client using the WASI program's standard input and output.

func NewWithIO

func NewWithIO(in io.Reader, out io.Writer) *Client

NewWithIO creates a client over protocol streams. It is useful for tests and does not open files or inspect the process environment.

func (*Client) Call

func (c *Client) Call(alias string, arguments map[string]any) (Reply, error)

Call invokes one declared connector tool alias and preserves its result.

func (*Client) Read

func (c *Client) Read(path string) (string, error)

Read requests the contents of one path declared with access: read.

func (*Client) Request

func (c *Client) Request(method string, fields map[string]any) (Reply, error)

Request sends one supported broker method with method-specific fields. Exit and Status remain caller-owned so exec/fetch callers can inspect them.

func (*Client) Return

func (c *Client) Return(stdout, stderr string, exit int) error

Return sends the final guest result to the runner. No further broker calls should be made after it succeeds.

type Error

type Error struct {
	Code   ErrorCode
	Landed bool
	Detail string
}

Error is returned when a broker response is refused, untrusted, or malformed.

func (*Error) Error

func (e *Error) Error() string

type ErrorCode

type ErrorCode string

ErrorCode identifies a broker failure without parsing its text.

const (
	ErrProtocol  ErrorCode = "protocol"
	ErrRefused   ErrorCode = "refused"
	ErrViolation ErrorCode = "violation"
	ErrUnknown   ErrorCode = "unknown"
	ErrFailed    ErrorCode = "failed"
)

type Reply

type Reply struct {
	ID        string   `json:"id,omitempty"`
	Result    string   `json:"result,omitempty"`
	Tools     []string `json:"tools,omitempty"`
	Stdout    string   `json:"stdout"`
	Stderr    string   `json:"stderr"`
	Exit      int      `json:"exit"`
	Stdin     string   `json:"stdin"`
	Status    int      `json:"status,omitempty"`
	Refused   string   `json:"refused,omitempty"`
	Violation bool     `json:"violation,omitempty"`
	Landed    bool     `json:"landed,omitempty"`
	Unknown   bool     `json:"unknown,omitempty"`
	Gated     bool     `json:"gated,omitempty"`
}

Reply preserves the runner fields callers may need to interpret. Exit is the native command status; Status is the HTTP status from fetch.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL