wire

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 19, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package wire defines the HTTP JSON types shared by the dispatcher and Go client. Request and log bytes may be represented as base64 strings at the server boundary or as decoded byte slices in the client.

Index

Constants

View Source 
const (
	// TagSpecVersionLegacy is a chain tagged with the pre-v1, non-standard
	// tag, including every chain of an executor that predates tag spec
	// reports: unsupported under tag spec v1.
	TagSpecVersionLegacy int64 = 0
	// TagSpecVersionV1 is TagSpecV1 (docs/tag-spec.md).
	TagSpecVersionV1 int64 = 1
)

Tag specification versions of an AttributionSchedule.

View Source 
const (
	TaggingEBPF      = "ebpf"      // Kernel tagger: every packet of a marked socket.
	TaggingUserspace = "userspace" // Pure-Go tagger: IPv4 UDP and ICMP datagrams only; TCP and TLS untagged.
	TaggingNone      = "none"      // Untagged.
)

Tagging modes of one address family or transport.

View Source 
const (
	// AdmissionReady executors accept submissions, subject to normal admission.
	AdmissionReady = "ready"
	// AdmissionMaintenance means the dispatcher's operator stopped admission.
	AdmissionMaintenance = "maintenance"
	// AdmissionOffline executors have sent no heartbeat on their current
	// control session yet; selection skips them.
	AdmissionOffline = "offline"
)

Admission states of a listed executor. An executor whose control session ended is not listed at all.

View Source 
const (
	MaxExperimentMetadata     = experiment.MaxExperimentMetadata
	MaxExperimentParticipants = experiment.MaxExperimentParticipants
)
View Source 
const (
	ProfileVersion        = 1
	MaxProfileBytes       = 8 << 20
	MaxProfilesPerAccount = 32
	// ProbeSHA256 identifies the Go 1.25.11 build shipped by the matching
	// dashboard. Clients verify the asset before applying a catalogue entry.
	ProbeSHA256 = "0135f2de557856f013e707d35225d3999895e217e55029c5d83cd5d595ffe91b"
)
View Source 
const (
	// AddressViaControl is the executor's control connection.
	AddressViaControl = "control"
	// AddressViaReflection is a ReflectAddress call over the other address
	// family (docs/operations/executor-discovery.md).
	AddressViaReflection = "reflection"
)

Ways the dispatcher observed an executor's address. Both are the peer address of a connection the executor authenticated with its own identity; neither is the executor's claim.

View Source 
const (
	ProbeConnected      = "connected"
	ProbeDisconnected   = "disconnected"
	ProbeAbandoned      = "abandoned"
	ProbeNeverConnected = "never_connected"
)

Probe status names, after RIPE Atlas's Connected, Disconnected, Abandoned and Never Connected.

View Source 
const (
	TagIPv4Works     = "system-ipv4-works"
	TagIPv6Works     = "system-ipv6-works"
	TagIPv4Capable   = "system-ipv4-capable"
	TagIPv6Capable   = "system-ipv6-capable"
	TagIPv4RFC1918   = "system-ipv4-rfc1918"
	TagResolvesA     = "system-resolves-a-correctly"
	TagResolvesAAAA  = "system-resolves-aaaa-correctly"
	TagIPv4Stable1d  = "system-ipv4-stable-1d"
	TagIPv4Stable30d = "system-ipv4-stable-30d"
	TagIPv4Stable90d = "system-ipv4-stable-90d"
	TagIPv6Stable1d  = "system-ipv6-stable-1d"
	TagIPv6Stable30d = "system-ipv6-stable-30d"
	TagIPv6Stable90d = "system-ipv6-stable-90d"
)

System tags, derived by the dispatcher from its own observations and the executor's reports; see docs/operations/executor-discovery.md.

View Source 
const (
	ResultFormat       = "debuglet-result"
	ResultVersion      = "1.1"
	ResultVersion10    = "1.0"
	RetryResultVersion = "1.2"
	MaxResultBytes     = 32 << 20
)
View Source 
const (
	SourceOperator           = "operator"
	SourceOwner              = "owner"
	SourceExecutorReported   = "executor-reported"
	SourceDispatcherObserved = "dispatcher-observed"
)

Source labels name who asserted a value. None of them means verified: an executor claim stays executor-reported however plausible it looks.

View Source 
const AbandonedAfter = 30 * 24 * time.Hour

AbandonedAfter is how long an executor stays disconnected before it is abandoned: 30 days after it was last known connected.

View Source 
const AttributionHistoryFormat = "debuglet-attribution-history-v1"
View Source 
const MaxHostTags = 8

MaxHostTags bounds the host tags of one executor.

View Source 
const MaxRunDetailBytes = MaxResultBytes

MaxRunDetailBytes accommodates retained configuration from before profiles had their own smaller upload bound, while keeping each response bounded.

View Source 
const TagSpecV1 = "debuglet-tag-v1"

TagSpecV1 is the first versioned packet-tag specification.

Variables

View Source 
var HostTags = []string{
	"home", "office", "datacentre", "academic", "cloud",
	"dsl", "cable", "fibre", "wifi", "mobile", "satellite",
	"nat",
}

HostTags is the fixed vocabulary of tags an executor's host may set in its configuration ([metadata] host_tags): where the host is, how it is connected, and whether it sits behind a NAT the host knows of.

View Source 
var ProbeStatuses = []string{ProbeConnected, ProbeDisconnected, ProbeAbandoned, ProbeNeverConnected}

ProbeStatuses lists the status names in their documented order.

Functions

func AttributionCertificateID 

func AttributionCertificateID(certificate []byte) string

AttributionCertificateID is the SHA-256 fingerprint of a DER certificate, matching the identity pinned by executor enrollment.

func AttributionHistoryBytes 

func AttributionHistoryBytes(p AttributionHistoryPayload) ([]byte, error)

AttributionHistoryBytes returns the stable JSON signed by the dispatcher. The statement itself is excluded to avoid recursive signatures.

func CanonicalHostTags 

func CanonicalHostTags(tags []string) ([]string, error)

CanonicalHostTags validates host tags against HostTags and returns them in vocabulary order. Unknown, repeated or too many tags are an error.

func CanonicalISDAS 

func CanonicalISDAS(text string) (string, bool)

CanonicalISDAS returns the canonical text of a concrete SCION ISD-AS, as the SCION libraries print it: a decimal ISD, then a decimal AS up to 2^32-1 or three colon-separated hexadecimal groups above it. Wildcards (ISD or AS 0) and malformed values are rejected.

func CanonicalReceiptPayload 

func CanonicalReceiptPayload(p AttributionReceiptPayload) ([]byte, error)

CanonicalReceiptPayload encodes a payload as canonical JSON: keys sorted, no whitespace, no HTML escaping.

func DatabaseSource 

func DatabaseSource(source string) bool

DatabaseSource recognises the source convention used by offline MMDB data.

func PacketsDigest 

func PacketsDigest(packets []AttributionVerifyPacket) string

PacketsDigest is "sha256:" and the hex SHA-256 over the big-endian uint16 length, the data and the int64 captured_at in Unix nanoseconds of every packet in order: the digest of an evidence bundle's packets.

func VerifyAttributionSchedule 

func VerifyAttributionSchedule(executor string, schedule AttributionSchedule, fingerprint string) error

VerifyAttributionSchedule requires the independently known certificate fingerprint of this executor, checks validity at the signed chain origin, and verifies every schedule field and the executor ID.

Types

type ASInfo 

type ASInfo struct {
	Number uint32 `json:"number"`
	Name   string `json:"name"`
	Prefix string `json:"prefix"`
}

type AddressMetadata 

type AddressMetadata struct {
	AddressSource string                `json:"address_source"`
	ASN           IPLookup[ASInfo]      `json:"asn"`
	Location      IPLookup[GeoLocation] `json:"location"`
}

AddressMetadata identifies the provenance of the lookup key without exposing the address itself in the public listing. The result already records the private keys as source_ip and public_host.

type AddressObservation 

type AddressObservation struct {
	Source string `json:"source"` // Always dispatcher-observed.
	Via    string `json:"via"`    // control or reflection.
	// ObservedAt is the Unix second of the last observation: the last
	// heartbeat of the control session that carries the address, or the
	// receipt of the last reflection call.
	ObservedAt int64 `json:"observed_at"`
	// LookupSource names the offline ASN database the prefix and ASN come
	// from, as in ip_metadata; null when no database is configured.
	LookupSource *string `json:"lookup_source"`
	// LookupReason is empty when the database knew the address; otherwise
	// it explains a null prefix and ASN, with the ip_metadata vocabulary.
	LookupReason string `json:"lookup_reason"`
}

AddressObservation describes how and when the dispatcher last observed the address of one family. The address itself is in Executor.AddressV4 or AddressV6, where is_public may hide it; this record never carries it.

type AddressObservations 

type AddressObservations struct {
	V4 *AddressObservation `json:"v4"`
	V6 *AddressObservation `json:"v6"`
}

AddressObservations has one record per address family, null when the dispatcher has observed no address of that family: for a connected executor in its current control session, for another within the retained history.

type Allowance 

type Allowance struct {
	Currency    string `json:"currency"`
	Granted     string `json:"granted"`
	Reserved    string `json:"reserved"`
	Consumed    string `json:"consumed"`
	Remaining   string `json:"remaining"`
	PricingRule string `json:"pricing_rule"`
}

Allowance is an account's usage allowance in TEST units: non-transferable usage credits an operator granted, not money. Amounts are decimal strings of integer TEST units. Granted is the sum of the account's grants; Consumed the price of its orders whose run has a settled outcome, credited or refunded alike; Reserved the price of the other orders of its paid intents; and Remaining is Granted - Consumed - Reserved.

type AllowanceGrant 

type AllowanceGrant struct {
	ID             int64     `json:"id"`
	Amount         string    `json:"amount"`
	Currency       string    `json:"currency"`
	Reason         string    `json:"reason"`
	IdempotencyKey string    `json:"idempotency_key"`
	GrantedBy      string    `json:"granted_by"`
	GrantedAt      time.Time `json:"granted_at"`
}

AllowanceGrant is one recorded grant. GrantedBy names the operator account that issued it.

type AllowanceGrantRequest 

type AllowanceGrantRequest struct {
	Amount         string `json:"amount,omitempty"`
	Reason         string `json:"reason"`
	IdempotencyKey string `json:"idempotency_key"`
}

AllowanceGrantRequest asks for a grant to an account. Amount is a decimal string of TEST units; empty asks for the dispatcher's default grant. The idempotency key makes a repeated request issue the grant once.

type AllowanceGrantResult 

type AllowanceGrantResult struct {
	Grant     AllowanceGrant `json:"grant"`
	Allowance Allowance      `json:"allowance"`
}

AllowanceGrantResult is a grant together with the account's allowance after it.

type AttributionCandidate 

type AttributionCandidate struct {
	ExecutorID string    `json:"executor_id"`
	RunID      string    `json:"run_id"`
	ActiveFrom time.Time `json:"active_from"`
	ActiveTo   time.Time `json:"active_to"`
	// IPSource is observed when the address is the one the dispatcher saw on
	// the executor's control connection, advertised when it is the executor's
	// own claim.
	IPSource string              `json:"ip_source"`
	Schedule AttributionSchedule `json:"schedule"`
	// DisclosedThrough is the latest epoch whose disclosed key is on record,
	// 0 when none is.
	DisclosedThrough int64 `json:"disclosed_through"`
	// DisclosedThroughAtNs is when the dispatcher recorded the key of
	// DisclosedThrough, in Unix nanoseconds; 0 when none is on record.
	DisclosedThroughAtNs int64 `json:"disclosed_through_at_ns"`
	// NextDisclosureAtNs is the earliest Unix nanoseconds the key of epoch
	// DisclosedThrough+1 may be disclosed; 0 when the schedule is unknown.
	NextDisclosureAtNs int64 `json:"next_disclosure_at_ns"`
}

AttributionCandidate is one run that was active from the queried address near the queried time. It names the run and its executor only, never the account that submitted it.

type AttributionCandidates 

type AttributionCandidates struct {
	IP string    `json:"ip"`
	At time.Time `json:"at"`
	// RetainedFrom is the start of the retained history: for an earlier
	// time the absence of a candidate is no evidence of absence.
	RetainedFrom time.Time              `json:"retained_from"`
	Candidates   []AttributionCandidate `json:"candidates"`
	// Truncated is set when more runs matched than the answer lists.
	Truncated bool `json:"truncated"`
	// Statement authenticates this dated lookup under the dispatcher's receipt
	// key. Its public key must be obtained through a separately trusted channel.
	Statement *AttributionReceipt `json:"statement,omitempty"`
}

AttributionCandidates answers GET /attribution/candidates.

type AttributionHistoryPayload 

type AttributionHistoryPayload struct {
	Format     string                `json:"format"`
	Dispatcher string                `json:"dispatcher"`
	SignedAt   time.Time             `json:"signed_at"`
	Lookup     AttributionCandidates `json:"lookup"`
}

AttributionHistoryPayload binds a dated lookup, including its schedule, run list and retention boundary, to a dispatcher and signing time. Format separates history statements from packet verification receipts.

type AttributionKey 

type AttributionKey struct {
	Epoch int64  `json:"epoch"`
	Key   []byte `json:"key"`
}

AttributionKey is one disclosed key of a chain.

type AttributionKeys 

type AttributionKeys struct {
	ExecutorID string           `json:"executor_id"`
	ChainID    string           `json:"chain_id"`
	Keys       []AttributionKey `json:"keys"`
	// NextEpoch is the from_epoch of the next page, nil on the last one.
	NextEpoch *int64 `json:"next_epoch"`
}

AttributionKeys answers GET /attribution/keys: one page of the disclosed keys of a chain in ascending epoch order. Undisclosed epochs are absent.

type AttributionReceipt 

type AttributionReceipt struct {
	KeyID     string `json:"key_id"`
	Payload   []byte `json:"payload"`
	Signature []byte `json:"signature"`
}

AttributionReceipt is a detached Ed25519 signature by the key KeyID over Payload, the canonical JSON of an AttributionReceiptPayload.

type AttributionReceiptGroup 

type AttributionReceiptGroup struct {
	ChainID    string `json:"chain_id"`
	Epoch      int64  `json:"epoch"`
	ExecutorID string `json:"executor_id"`
	Method     string `json:"method"`
	Packets    []int  `json:"packets"`
	Reason     string `json:"reason"`
	RunID      string `json:"run_id"`
	Source     string `json:"source"`
	Verdict    string `json:"verdict"`
}

AttributionReceiptGroup is one group verdict as a receipt records it.

type AttributionReceiptKey 

type AttributionReceiptKey struct {
	KeyID     string     `json:"key_id"`
	PublicKey []byte     `json:"public_key"`
	ValidFrom time.Time  `json:"valid_from"`
	ValidTo   *time.Time `json:"valid_to"`
}

AttributionReceiptKey is one key that verifies receipts, valid for receipts whose query_at is at or after ValidFrom and, when ValidTo is set, before it.

type AttributionReceiptKeys 

type AttributionReceiptKeys struct {
	Keys []AttributionReceiptKey `json:"keys"`
}

AttributionReceiptKeys answers GET /attribution/receipt-keys.

type AttributionReceiptPayload 

type AttributionReceiptPayload struct {
	APIVersion    string                    `json:"api_version"`
	Dispatcher    string                    `json:"dispatcher"`
	Groups        []AttributionReceiptGroup `json:"groups"`
	PacketsDigest string                    `json:"packets_digest"`
	QueryAt       string                    `json:"query_at"`
}

AttributionReceiptPayload is what a receipt signs. QueryAt is the dispatcher's clock when it answered; the callers' capture times enter only through PacketsDigest, so a receipt shows what was asked and answered when, not when a packet was observed. Its fields are in the order of their JSON names, which CanonicalReceiptPayload relies on.

type AttributionSchedule 

type AttributionSchedule struct {
	// ChainID identifies the chain: the lowercase hex of the first 16 bytes
	// of SHA-256(K0).
	ChainID string `json:"chain_id"`
	// K0 is the chain anchor, the key of epoch 0; every disclosed key hashes
	// to it.
	K0 []byte `json:"k0"`
	// T0UnixNs is the start of epoch 0 in Unix nanoseconds.
	T0UnixNs int64 `json:"t0_unix_ns"`
	// EpochSeconds is the epoch length I in seconds.
	EpochSeconds int64 `json:"epoch_seconds"`
	// DisclosureDelayEpochs is the disclosure delay d in epochs; zero is an
	// executor that predates it, whose tags a verifier must not accept.
	DisclosureDelayEpochs int64 `json:"disclosure_delay_epochs"`
	// ChainLength is L, the number of epochs the chain serves; zero is unknown.
	ChainLength int64 `json:"chain_length"`
	// TagSpec is the tag specification version the executor reported when it
	// registered the chain: TagSpecVersionV1, or TagSpecVersionLegacy for an
	// executor that did not report debuglet-tag-v1. Verifiers of tag spec v1
	// must treat a legacy chain as unsupported, not as a mismatch.
	TagSpec int64 `json:"tag_spec"`
	// OperatorProof is signed by the executor's enrolled TLS key. Offline
	// trust requires a separately known certificate fingerprint.
	OperatorProof *AttributionScheduleProof `json:"operator_proof,omitempty"`
}

AttributionSchedule is the public TESLA schedule of one executor chain. The key of epoch t covers the packets sent from T0UnixNs + t*EpochSeconds to T0UnixNs + (t+1)*EpochSeconds and is disclosed no earlier than T0UnixNs + (t+DisclosureDelayEpochs)*EpochSeconds. Its field names follow those of GET /executors/{id}/tesla.

type AttributionScheduleProof 

type AttributionScheduleProof struct {
	Certificate []byte `json:"certificate"`
	Signature   []byte `json:"signature"`
}

AttributionScheduleProof authenticates schedule parameters under an executor's enrolled TLS key. The certificate is evidence of a signature, not a trust root: consumers must independently pin its fingerprint.

func SignAttributionSchedule 

func SignAttributionSchedule(executor string, schedule AttributionSchedule, identity tls.Certificate) (*AttributionScheduleProof, error)

SignAttributionSchedule uses the existing enrolled TLS identity; no new signing key or private material is included in the proof.

type AttributionState 

type AttributionState struct {
	State               string `json:"state"`                 // available or unavailable.
	Reason              string `json:"reason"`                // Empty when available; epoch_zero, chain_exhausted, refresh_failing, disclosure_held, clock_unready, clock_drift, untagged.
	Epoch               int64  `json:"epoch"`                 // Current key-schedule epoch.
	InstalledEpoch      *int64 `json:"installed_epoch"`       // Oldest epoch a kernel tagger may still sign with; null when none holds a key.
	LastRefreshAt       *int64 `json:"last_refresh_at"`       // Oldest last successful kernel key install; null without one.
	RefreshError        string `json:"refresh_error"`         // Short error of a failing kernel key refresh; empty when none fails.
	DisclosureHeldSince *int64 `json:"disclosure_held_since"` // When an installed key started holding disclosure back; null when not held.
}

AttributionState is the executor's report of whether packets it tags now can be attributed once their TESLA key is disclosed. Its times are the dispatcher receipt time minus an executor-reported age, in Unix seconds, so they share ObservedAt's clock. Available is an executor claim, not a verification.

type AttributionVerifyBudget 

type AttributionVerifyBudget struct {
	Limit     int64     `json:"limit"`
	Remaining int64     `json:"remaining"`
	ResetsAt  time.Time `json:"resets_at"`
}

AttributionVerifyBudget is the budget of one chain epoch in candidate trials, shared by every requester: an executor query charges one trial per candidate run it tests. ResetsAt is when the epoch's key is due for disclosure; from then on the group is checked against the disclosed key.

type AttributionVerifyGroup 

type AttributionVerifyGroup struct {
	Source       string                   `json:"source"`
	Epoch        int64                    `json:"epoch"`
	ChainID      string                   `json:"chain_id"`
	ExecutorID   string                   `json:"executor_id"`
	RunID        string                   `json:"run_id"`
	Verdict      string                   `json:"verdict"`
	Reason       string                   `json:"reason"`
	Method       string                   `json:"method"`
	Packets      []int                    `json:"packets"`
	Budget       *AttributionVerifyBudget `json:"budget,omitempty"`
	PendingUntil *time.Time               `json:"pending_until,omitempty"`
}

AttributionVerifyGroup is the verdict of one packet group: the packets of one source address in one epoch of one chain. Packets are indices into the request's packets. Budget is set for a group that has a chain; PendingUntil, for a pending group, is when its key is due for disclosure.

type AttributionVerifyPacket 

type AttributionVerifyPacket struct {
	Data       []byte    `json:"data"`
	CapturedAt time.Time `json:"captured_at"`
}

AttributionVerifyPacket is one captured packet: the first min(64, Total Length) bytes of the IPv4 packet and the time the caller says it was captured.

type AttributionVerifyRequest 

type AttributionVerifyRequest struct {
	Packets []AttributionVerifyPacket `json:"packets"`
}

AttributionVerifyRequest is the body of POST /attribution/verify.

type AttributionVerifyResponse 

type AttributionVerifyResponse struct {
	Groups  []AttributionVerifyGroup `json:"groups"`
	Receipt AttributionReceipt       `json:"receipt"`
}

AttributionVerifyResponse answers POST /attribution/verify.

type Cancellation 

type Cancellation struct {
	ID              string          `json:"id"`
	RequestID       string          `json:"request_id"`
	ExecutorID      string          `json:"executor_id"`
	OriginalBinding *ControlBinding `json:"original_binding"`
	RequestedAt     time.Time       `json:"requested_at"`
	AttemptedAt     *time.Time      `json:"attempted_at"`
	AcknowledgedAt  *time.Time      `json:"acknowledged_at"`
	CheckedAt       time.Time       `json:"checked_at"`
	Disposition     string          `json:"disposition"`
	Reason          string          `json:"reason"`
	State           string          `json:"state"`
	Error           string          `json:"error"`
}

Cancellation separates a durable request, an executor acknowledgement and the immutable run result. An attempted delivery does not confirm receipt.

type CapabilityObservation 

type CapabilityObservation struct {
	State      string `json:"state"`
	ObservedAt *int64 `json:"observed_at"`
	ExpiresAt  *int64 `json:"expires_at"`
}

CapabilityObservation distinguishes an expired report from absent or malformed metadata while legacy Capabilities continues to expire to null.

type CapabilityReport 

type CapabilityReport struct {
	SchemaVersion   int      `json:"schema_version"`
	Protocols       []string `json:"protocols"`
	EnforcementMode string   `json:"enforcement_mode"`
	// Tagging is the report's tagging mode; null when the report had none.
	// Additive within result format 1.1.
	Tagging *TaggingMode `json:"tagging"`
	// Added within vantage_point schema 1; absent in earlier files.
	EnforcementReason string      `json:"enforcement_reason"`
	ICMP              *ProbeState `json:"icmp"`
}

type ChainTransfer 

type ChainTransfer struct {
	ID        int64     `json:"id"`
	Kind      string    `json:"kind"`
	Amount    string    `json:"amount"`
	Currency  string    `json:"currency"`
	Receiver  string    `json:"receiver"`
	State     string    `json:"state"`
	Digest    string    `json:"digest"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

ChainTransfer is one outbound chain transfer. Kind is payout or refund; State is reserved, sent, confirmed, failed or unknown, where unknown means the outcome is not known yet, never that it failed.

type ClockReport 

type ClockReport struct {
	State            string `json:"state"`              // synced, unsynced or unknown.
	EstimatedErrorNS *int64 `json:"estimated_error_ns"` // Kernel esterror; null unknown.
	MaxErrorNS       *int64 `json:"max_error_ns"`       // Kernel maxerror; null unknown.
	ErrorBoundNS     int64  `json:"error_bound_ns"`     // Operator-configured bound on the estimated error.
	Readiness        string `json:"readiness"`          // ready, degraded or unknown.
	Reason           string `json:"reason"`             // Empty unless degraded: unsynced or error_exceeds_bound.
}

ClockReport is the executor's reading of its kernel clock discipline (adjtimex). The errors are the kernel's own estimates, maintained by a time daemon, not measured bounds.

type Connectivity 

type Connectivity struct {
	SchemaVersion int            `json:"schema_version"`
	IPv4          Reachability   `json:"ipv4"`
	IPv6          Reachability   `json:"ipv6"`
	TCPListener   Reachability   `json:"tcp_listener"`
	UDPListener   Reachability   `json:"udp_listener"`
	SCIONListener Reachability   `json:"scion_listener"`
	SCIONHost     ObservedString `json:"scion_host"`
	SCIONPaths    Reachability   `json:"scion_paths"`
	Disagreements []string       `json:"disagreements"`
}

Connectivity records bounded observations against operator-controlled peers. A successful test describes that peer and transport at that time; it does not establish reachability to every destination or port. Addresses and endpoints are returned only to operators and in owner-visible results.

func CloneConnectivity 

func CloneConnectivity(in *Connectivity, now time.Time, private bool) *Connectivity

CloneConnectivity detaches pointer fields for registry and result snapshots.

type ControlBinding 

type ControlBinding struct {
	DispatcherIncarnation string `json:"dispatcher_incarnation"`
	SessionID             string `json:"session_id"`
}

ControlBinding identifies one nonsecret executor control session.

type Economics 

type Economics struct {
	PaymentMethods []string `json:"payment_methods"`
	ChainPayments  bool     `json:"chain_payments"`
	Allowances     bool     `json:"allowances"`
}

Economics states which payment features this dispatcher offers the account, so a client can hide what is unavailable. It reports configuration, not a balance.

type Executor 

type Executor struct {
	Connectivity           *Connectivity            `json:"connectivity,omitempty"`
	AdmissionLimits        *ExecutorAdmissionLimits `json:"admission_limits,omitempty"`
	CapabilityObservation  *CapabilityObservation   `json:"capability_observation,omitempty"`
	Capabilities           *ExecutorCapabilities    `json:"capabilities,omitempty"`
	ID                     string                   `json:"id"`
	Ready                  bool                     `json:"ready"`
	LastSeen               int64                    `json:"last_seen"`
	Version                string                   `json:"version"`
	TeslaDelaySec          int64                    `json:"tesla_delay_sec"`
	TeslaAnchorTimestampNs int64                    `json:"tesla_anchor_timestamp_ns"`
	TeslaAnchorKey         []byte                   `json:"tesla_anchor_key"` // k_0, the public chain anchor
	PricePerBw             int64                    `json:"price_per_bw"`
	Currency               string                   `json:"currency"`
	// Admission is ready, maintenance or offline; empty from older dispatchers.
	Admission  string          `json:"admission"`
	Display    ExecutorDisplay `json:"display"`
	SCIONISDAS ObservedString  `json:"scion_isd_as"`
	// Listeners are the transports the executor can open run listeners on.
	Listeners ObservedList `json:"listeners"`
	// Clock is the executor-reported kernel clock state. Host platform detail
	// is operator-only and never part of this public listing.
	Clock      ObservedClock `json:"clock"`
	IPMetadata *IPMetadata   `json:"ip_metadata,omitempty"`
	// ProbeAddressing (API 1.16) adds the RIPE Atlas-style is_public,
	// address, prefix and ASN fields of each address family.
	ProbeAddressing
	// ProbeStatus (API 1.17) adds the RIPE Atlas-style status history and
	// host and system tags.
	ProbeStatus
}

Executor is one executor as reported by GET executors.

func (Executor) Location 

func (e Executor) Location() (city, country LabelledString)

Location prefers explicit dispatcher-operator or owner-reported labels. Automatic location is used only when neither city nor country is set.

type ExecutorAdmissionLimits 

type ExecutorAdmissionLimits struct {
	Scheduling      bool   `json:"scheduling"`
	MinTimeoutMS    int64  `json:"min_timeout_ms"`
	MaxTimeoutMS    int64  `json:"max_timeout_ms"`
	MaxBandwidthBPS int64  `json:"max_bandwidth_bps"`
	PriceUnit       string `json:"price_unit"`
}

ExecutorAdmissionLimits describes the dispatcher policy's numeric domain, not free resources. A complete scheduled reservation must also fit the scheduler's time range and the executor's remaining advertised capacity.

type ExecutorCapabilities 

type ExecutorCapabilities struct {
	SchemaVersion         uint32            `json:"schema_version"`
	ObservedAt            int64             `json:"observed_at"`             // Dispatcher receipt time, Unix seconds.
	Protocols             []string          `json:"protocols"`               // Positive tcp, tls, udp, icmp (IPv4), scion support.
	EnforcementMode       string            `json:"enforcement_mode"`        // Selected ebpf/fallback backend; empty unknown. Not proof of packet coverage.
	AdvertisedCapacityBPS *int64            `json:"advertised_capacity_bps"` // Total reported bandwidth, not free capacity; null unknown.
	Attribution           *AttributionState `json:"attribution"`             // Null unknown, including executors that predate it.
	Tagging               *TaggingMode      `json:"tagging"`                 // Null unknown, including executors that predate it.
	// EnforcementReason says why the counter is fallback: configured,
	// no_interface, not_permitted, unsupported or attach_failed. Empty when
	// unknown or ebpf.
	EnforcementReason string `json:"enforcement_reason"`
	// ICMP is the executor's raw ICMPv4 socket probe; null unknown.
	ICMP *ProbeState `json:"icmp"`
}

ExecutorCapabilities is a current executor-reported observation, not a destination reachability, admission or packet-attribution guarantee. An absent object means unknown, including older peers, stale reports and unknown versions.

type ExecutorDisplay 

type ExecutorDisplay struct {
	DisplayName LabelledString `json:"display_name"`
	City        LabelledString `json:"city"`
	Country     LabelledString `json:"country"` // ISO 3166-1 alpha-2.
	Network     LabelledString `json:"network"`
}

ExecutorDisplay is operator presentation metadata from the dispatcher configuration. Location is at most city and country and is never inferred.

type ExecutorEarnings 

type ExecutorEarnings struct {
	Currency       string          `json:"currency"`
	TotalIncome    string          `json:"total_income"`
	CurrentBalance string          `json:"current_balance"`
	Transfers      []ChainTransfer `json:"transfers"`
	Payouts        string          `json:"payouts"`
}

ExecutorEarnings is what an executor earned, as the dispatcher records it, and the outbound chain transfers that name the executor. Amounts are decimal strings of integer base units of Currency. Payouts is "enabled" or "disabled"; nothing is paid out while blockchain payments are disabled.

type Experiment 

type Experiment = experiment.Experiment

Experiment is a one-shot readiness result for one admitted batch. Metadata is opaque application data and grants no permission to contact a peer.

type ExperimentParticipant 

type ExperimentParticipant = experiment.ExperimentParticipant

type FieldError 

type FieldError struct {
	Field   string `json:"field"`
	Code    string `json:"code"`
	Message string `json:"message"`
	OrderID *int64 `json:"order_id,omitempty"`
}

FieldError identifies a refused request field. Field is a dotted request path, Code is a stable reason, and Message is explanatory text, not data to parse. OrderID is present when the failure identifies an order in a batch.

type GeoLocation 

type GeoLocation struct {
	Country   string `json:"country"`
	City      string `json:"city"`
	Precision string `json:"precision"`
}

GeoLocation is approximate and deliberately excludes coordinates and region detail. Precision is country or city; city is optional for country precision.

type HostPlatform 

type HostPlatform struct {
	OS            *string `json:"os"`   // Go GOOS.
	Arch          *string `json:"arch"` // Go GOARCH.
	KernelRelease *string `json:"kernel_release"`
	CPUs          *int64  `json:"cpus"`
	MemoryBytes   *uint64 `json:"memory_bytes"`
	BuildVersion  *string `json:"build_version"`
}

HostPlatform is operator-only host detail. Null values are unknown.

type IPLookup 

type IPLookup[T any] struct {
	Value      *T      `json:"value"`
	Source     *string `json:"source"`
	ObservedAt int64   `json:"observed_at"`
	Reason     string  `json:"reason"`
}

IPLookup records an offline database lookup at registration. Reason is empty for a known value; otherwise it explains why Value is null. Source identifies the database and its build epoch, including for a negative lookup.

type IPMetadata 

type IPMetadata struct {
	Reported       *AddressMetadata `json:"reported,omitempty"` // Separate hello claim when it differs from the observed control address.
	Observed       AddressMetadata  `json:"observed"`
	Advertised     AddressMetadata  `json:"advertised"`
	LocationOptOut bool             `json:"location_opt_out"`
	Disagreements  []string         `json:"disagreements"`
}

type LabelledObservation 

type LabelledObservation struct {
	Value      *string    `json:"value"`
	Source     *string    `json:"source"`
	ObservedAt *time.Time `json:"observed_at"`
	Stale      *bool      `json:"stale"`
}

LabelledObservation is an expiring value as known at admission: Stale says it had outlived its lifetime. All fields are null together.

type LabelledReport 

type LabelledReport[T any] struct {
	Value      *T         `json:"value"`
	Source     *string    `json:"source"`
	ObservedAt *time.Time `json:"observed_at"`
	Stale      *bool      `json:"stale"`
}

LabelledReport is an expiring report as known at admission, like LabelledObservation. All fields are null together.

type LabelledString 

type LabelledString struct {
	Value  *string `json:"value"`
	Source *string `json:"source"`
}

type LogEntry 

type LogEntry[Binary ~string | ~[]byte] struct {
	ID        int64  `json:"id"`
	Timestamp string `json:"timestamp"`
	Output    Binary `json:"output"`
}

LogEntry is one stored output chunk. Output is base64 text on the server and the exact guest bytes in the client; Timestamp is the server's opaque string.

type LogPage 

type LogPage[Binary ~string | ~[]byte] struct {
	State   string             `json:"state"`
	Error   string             `json:"error"`
	After   int64              `json:"after"`
	Logs    []LogEntry[Binary] `json:"logs"`
	HasMore bool               `json:"has_more"`
	Output  OutputStatus       `json:"output"`
}

LogPage is one page of guest output. The server omits an empty Error when serializing its response; clients may also receive the explicit empty string.

type Measurement 

type Measurement struct {
	ID     string           `json:"id"`
	Runs   []MeasurementRun `json:"runs"`
	Total  int64            `json:"total"`
	Limit  int64            `json:"limit"`
	Offset int64            `json:"offset"`
}

type MeasurementPage 

type MeasurementPage struct {
	Measurements []MeasurementSummary `json:"measurements"`
	Total        int64                `json:"total"`
	Counts       map[string]int64     `json:"counts"`
	Limit        int64                `json:"limit"`
	Offset       int64                `json:"offset"`
}

type MeasurementRun 

type MeasurementRun struct {
	RunID       string `json:"run_id"`
	ExecutorID  string `json:"executor_id"`
	OrderID     int64  `json:"order_id"`
	State       string `json:"state"`
	Label       string `json:"label"`
	ProgramName string `json:"program_name"`
}

MeasurementRun is a bounded reference. Load RunDetail for its configuration.

type MeasurementSummary 

type MeasurementSummary struct {
	ID             string    `json:"id"`
	Label          string    `json:"label"`
	State          string    `json:"state"`
	Children       int64     `json:"children"`
	ScheduledStart time.Time `json:"scheduled_start"`
}

type MeasurementTemplate 

type MeasurementTemplate struct {
	ID                 string            `json:"id"`
	Version            int               `json:"version"`
	Name               string            `json:"name"`
	Description        string            `json:"description"`
	ProgramSHA256      string            `json:"program_sha256"`
	ProgramAsset       string            `json:"program_asset"`
	Arguments          TemplateArguments `json:"arguments"`
	RequiredTransports []string          `json:"required_transports"`
	DefaultPolicy      Policy            `json:"default_policy"`
}

type ObservedClock 

type ObservedClock struct {
	Value      *ClockReport `json:"value"`
	Source     *string      `json:"source"`
	ObservedAt *int64       `json:"observed_at"` // Dispatcher receipt time, Unix seconds.
}

ObservedClock is the live clock observation; all fields are null together when unknown or expired.

type ObservedList 

type ObservedList struct {
	Value      []string `json:"value"`
	Source     *string  `json:"source"`
	ObservedAt *int64   `json:"observed_at"` // Dispatcher receipt time, Unix seconds.
}

ObservedList is an expiring list observation. A null Value is unknown; an empty one was observed as empty.

type ObservedString 

type ObservedString struct {
	Value      *string `json:"value"`
	Source     *string `json:"source"`
	ObservedAt *int64  `json:"observed_at"` // Dispatcher receipt time, Unix seconds.
}

ObservedString is an expiring observation in the live executor view. All three fields are null when it is unknown or has expired.

type OrderHistory 

type OrderHistory struct {
	Intents []OrderHistoryIntent `json:"intents"`
	Next    string               `json:"next"`
}

OrderHistory is one page of the account's payment intents, newest expiry first. Next is the cursor of the following page, empty on the last one.

type OrderHistoryIntent 

type OrderHistoryIntent struct {
	ID          string              `json:"id"`
	Method      string              `json:"method"`
	Status      string              `json:"status"`
	Price       string              `json:"price"`
	Currency    string              `json:"currency"`
	PricingRule string              `json:"pricing_rule"`
	ExpiresAt   time.Time           `json:"expires_at"`
	Orders      []OrderHistoryOrder `json:"orders"`
}

OrderHistoryIntent is one payment intent with its orders. Status is one of outstanding, paid, refunded, expired or aborted, or unknown for a value this version does not name. PricingRule is empty when the dispatcher did not record the rule the intent was priced with.

type OrderHistoryOrder 

type OrderHistoryOrder struct {
	OrderID    int64  `json:"order_id"`
	ExecutorID string `json:"executor_id"`
	Price      string `json:"price"`
	Currency   string `json:"currency"`
	Settlement string `json:"settlement"`
	RunID      string `json:"run_id,omitempty"`
}

OrderHistoryOrder is one order of an intent. Settlement is pending, credited or refunded, as in RunCost. RunID names the admitted run and is empty while the order has not been admitted.

type OutputStatus 

type OutputStatus struct {
	State       string `json:"state"`
	FinalCursor *int64 `json:"final_cursor"`
	LossReason  string `json:"loss_reason"`
}

OutputStatus describes the stored output independently of the workload state. State is open: unknown future values do not establish completeness. A final cursor is present only for complete or truncated output, and is zero if empty.

type Policy 

type Policy struct {
	FloorBW     int64    `json:"floor_bw"`
	CeilBW      int64    `json:"ceil_bw"`
	TimeoutMS   int64    `json:"timeout_ms"`
	Addresses   []string `json:"addresses"`
	RequireICMP bool     `json:"require_icmp"`
	ListenUDP   bool     `json:"listen_udp"`
	ListenTCP   bool     `json:"listen_tcp"`
	ListenSCION bool     `json:"listen_scion"`
}

Policy is the network policy requested for a debuglet.

type ProbeAddressing 

type ProbeAddressing struct {
	IsPublic            *bool                `json:"is_public"`
	AddressV4           *string              `json:"address_v4"`
	AddressV6           *string              `json:"address_v6"`
	PrefixV4            *string              `json:"prefix_v4"`
	PrefixV6            *string              `json:"prefix_v6"`
	ASNV4               *uint32              `json:"asn_v4"`
	ASNV6               *uint32              `json:"asn_v6"`
	AddressObservations *AddressObservations `json:"address_observations"`
}

ProbeAddressing is the RIPE Atlas-style addressing of an executor in the public listing, embedded in Executor. A dispatcher of API 1.16 or later always sends every field, null when unknown; all are absent from dispatchers older than API 1.16, which a client reads as unknown.

AddressV4 and AddressV6 are the last addresses the dispatcher itself observed for each family. They are null when none was observed, and in the public listing also when IsPublic is false or the observed address is not globally routable; an operator always sees them. Non-global observations carry lookup_reason "non_global" and no prefix or ASN. Prefixes and ASNs are looked up from those addresses in the offline ASN database and stay public for a private executor, as RIPE Atlas does.

type ProbeState 

type ProbeState struct {
	State  string `json:"state"`  // available or unavailable.
	Reason string `json:"reason"` // Empty when available; disabled, not_permitted, ping_socket_only or unsupported.
}

ProbeState is an executor-reported local probe outcome.

type ProbeStatus 

type ProbeStatus struct {
	Status         *ProbeStatusName `json:"status"`
	StatusSince    *int64           `json:"status_since"`
	FirstConnected *int64           `json:"first_connected"`
	LastConnected  *int64           `json:"last_connected"`
	TotalUptime    *int64           `json:"total_uptime"`
	Tags           []string         `json:"tags"`
}

ProbeStatus is the RIPE Atlas-style status history and tags of an executor, embedded in Executor. A dispatcher of API 1.17 or later always sends every field; all are absent from older dispatchers.

Times are Unix seconds. FirstConnected and LastConnected are null for an executor that never connected; LastConnected of a connected executor is its last heartbeat. TotalUptime counts connected seconds since the dispatcher began recording them (schema 24). Tags lists the host tags, then the system tags, which start with "system-".

type ProbeStatusName 

type ProbeStatusName struct {
	Name  string `json:"name"`
	Since *int64 `json:"since"`
}

ProbeStatusName is a status with the Unix second it began.

type Profile 

type Profile struct {
	ID     string        `json:"id"`
	Config ProfileConfig `json:"config"`
}

type ProfileConfig 

type ProfileConfig struct {
	Version    int                `json:"version"`
	Name       string             `json:"name"`
	Program    ProfileProgram     `json:"program"`
	ExecutorID string             `json:"executor_id"`
	Args       []string           `json:"args"`
	Policy     Policy             `json:"policy"`
	Template   *TemplateReference `json:"template,omitempty"`
}

ProfileConfig is reusable: it deliberately contains neither an absolute scheduled start nor any payment or account credential. Unknown fields are rejected by the API rather than silently retained.

type ProfileProgram 

type ProfileProgram struct {
	SHA256 string `json:"sha256"`
	Wasm   []byte `json:"wasm"`
}

type ProfileSummary 

type ProfileSummary struct {
	ID            string `json:"id"`
	Name          string `json:"name"`
	ProgramSHA256 string `json:"program_sha256"`
}

ProfileSummary excludes the program and arguments so listing remains small.

type Quote 

type Quote struct {
	PricingRule string        `json:"pricing_rule"`
	Currency    string        `json:"currency"`
	Unit        string        `json:"unit"`
	Total       string        `json:"total"`
	Orders      []QuotedOrder `json:"orders"`
	Errors      []FieldError  `json:"errors"`
}

Quote is the price of a batch as the dispatcher's pricing authority computes it, without reserving anything. Amounts are decimal strings of integer base units of Currency, described by Unit. Total is empty unless every order was priced; Errors then lists the problems of the batch as a whole and each QuotedOrder its own.

type QuotedOrder 

type QuotedOrder struct {
	OrderID    int64        `json:"order_id"`
	ExecutorID string       `json:"executor_id"`
	Price      string       `json:"price"`
	Errors     []FieldError `json:"errors"`
}

QuotedOrder is one order of a Quote, in request order. Price is empty when the order could not be priced, and Errors states why.

type Reachability 

type Reachability struct {
	State      string `json:"state"` // reachable, unreachable or untested.
	Reason     string `json:"reason"`
	Source     string `json:"source"`
	ObservedAt *int64 `json:"observed_at"`
	ExpiresAt  *int64 `json:"expires_at"`
	Stale      bool   `json:"stale"`
	Address    string `json:"address,omitempty"`
	Endpoint   string `json:"endpoint,omitempty"`
}

Reachability distinguishes an unsuccessful test from an unperformed one. Missing times mean no test was performed. Stale retains the last outcome without renewing its authority. Endpoint identifies the one tested peer or listener; Address is the reflector-observed egress address, when available.

func (Reachability) FreshReachable 

func (r Reachability) FreshReachable(now time.Time) bool

FreshReachable never treats an expired or untested observation as positive.

type Recovery 

type Recovery struct {
	ID                    string              `json:"id"`
	ExecutorID            string              `json:"executor_id"`
	State                 string              `json:"state"`
	Error                 string              `json:"error"`
	CheckedAt             time.Time           `json:"checked_at"`
	OriginalBinding       *ControlBinding     `json:"original_binding"`
	ControlStatus         string              `json:"control_status"`
	Observation           RecoveryObservation `json:"observation"`
	AllocationReclaimedAt *time.Time          `json:"allocation_reclaimed_at,omitempty"`
}

Recovery separates stored outcome from control availability and an optional dated executor observation. No classification authorizes replay.

type RecoveryObservation 

type RecoveryObservation struct {
	Classification string            `json:"classification"`
	Observer       *RecoveryObserver `json:"observer"`
	ReceivedAt     *time.Time        `json:"received_at"`
	CurrentAtCheck *bool             `json:"current_at_check"`
	Retained       *RetainedRun      `json:"retained"`
}

RecoveryObservation carries provenance only for a validated executor reply. A received reply can already be historical when CurrentAtCheck is false.

type RecoveryObserver 

type RecoveryObserver struct {
	ExecutorID string         `json:"executor_id"`
	Binding    ControlBinding `json:"binding"`
}

type Request 

type Request[Binary ~string | ~[]byte] struct {
	// OrderID must be unique within one batch.
	OrderID int64 `json:"order_id"`
	// StartTimestamp is an optional Unix epoch start time.
	StartTimestamp *int64   `json:"start_time,omitempty"`
	ExecutorID     string   `json:"executor_id"`
	Args           []string `json:"args,omitempty"`
	Wasm           Binary   `json:"wasm"`
	Policy         Policy   `json:"policy"`
	Label          string   `json:"label,omitempty"`
	ProgramName    string   `json:"program_name,omitempty"`
}

Request describes one debuglet in a batch. Binary is a base64 string on the server and a byte slice (encoded by encoding/json) in the client.

type Result 

type Result struct {
	Format       string             `json:"format"`
	Version      string             `json:"version"`
	RunID        string             `json:"run_id"`
	ExecutorID   string             `json:"executor_id"`
	Attempt      *ControlBinding    `json:"attempt"`
	Provenance   *ResultProvenance  `json:"provenance"`
	Outcome      ResultOutcome      `json:"outcome"`
	Timing       ResultTiming       `json:"timing"`
	Output       ResultOutput       `json:"output"`
	Verification ResultVerification `json:"verification"`
}

Result is a portable snapshot, not proof that a measurement is true. Missing historical admission facts remain nil. Workload outcome and output finality are independent observations.

type ResultOutcome 

type ResultOutcome struct {
	State    string `json:"state"`
	Error    string `json:"error"`
	ExitCode *int64 `json:"exit_code"`
}

type ResultOutput 

type ResultOutput struct {
	Status  OutputStatus       `json:"status"`
	Entries []LogEntry[[]byte] `json:"entries"`
}

type ResultProvenance 

type ResultProvenance struct {
	Retry              *RetryLink     `json:"retry,omitempty"`
	RunID              string         `json:"run_id"`
	ExecutorID         string         `json:"executor_id"`
	Attempt            ControlBinding `json:"attempt"`
	AdmittedAt         time.Time      `json:"admitted_at"`
	WorkloadSHA256     string         `json:"workload_sha256"`
	Arguments          []string       `json:"arguments"`
	AdmittedPolicy     Policy         `json:"admitted_policy"`
	HostPolicy         string         `json:"host_policy"`
	ExecutorSoftware   *string        `json:"executor_software"`
	DispatcherSoftware *string        `json:"dispatcher_software"`
	DispatcherRevision *string        `json:"dispatcher_revision"`
	CertificateSHA256  *string        `json:"certificate_sha256"`
	VantagePoint       *VantagePoint  `json:"vantage_point"`
}

ResultProvenance is captured once when admission commits. Executor software is the executor session's report, not an independent binary attestation. AdmittedPolicy describes the dispatched request; actual host policy and enforcement are unavailable to this record.

type ResultTiming 

type ResultTiming struct {
	ObservedAt         time.Time  `json:"observed_at"`
	ScheduledStart     *time.Time `json:"scheduled_start"`
	ReservedUntil      *time.Time `json:"reserved_until"`
	StartedAt          *time.Time `json:"started_at"`
	FinishedAt         *time.Time `json:"finished_at"`
	ClockUncertaintyNS *int64     `json:"clock_uncertainty_ns"`
}

ScheduledStart and ReservedUntil describe admission's reservation, not measured execution times. ClockUncertaintyNS is nil when no bound is known.

type ResultVerification 

type ResultVerification struct {
	Attribution      string `json:"attribution"`
	PacketEvidence   string `json:"packet_evidence"`
	MeasurementTruth string `json:"measurement_truth"`
}

Attribution identifies the admission source only. It does not authenticate packet evidence or establish measurement truth.

type RetainedRun 

type RetainedRun struct {
	OriginalBinding *ControlBinding `json:"original_binding"`
	Started         bool            `json:"started"`
	StartedAt       *time.Time      `json:"started_at"`
	StartTime       *time.Time      `json:"start_time"`
}

RetainedRun describes stored metadata, not an executable or terminal result. Started records a durable start marker, not proof the guest actually ran. 

type RetryLink struct {
	ParentRunID string `json:"parent_run_id"`
	RequestID   string `json:"request_id"`
}

RetryLink identifies an explicit new attempt. Reusing RequestID with the same parent and frozen request recovers the attempt; a new ID requests new work.

type RetryReceipt 

type RetryReceipt struct {
	RetryLink
	RunID string `json:"run_id,omitempty"`
}

type RunCost 

type RunCost struct {
	Currency   string  `json:"currency"`
	Unit       string  `json:"unit"`
	Reserved   string  `json:"reserved"`
	Charged    *string `json:"charged"`
	Settlement string  `json:"settlement"`
}

type RunDetail 

type RunDetail struct {
	Execution  *RunExecution           `json:"execution"`
	RunID      string                  `json:"run_id"`
	ExecutorID string                  `json:"executor_id"`
	BatchID    string                  `json:"batch_id"`
	OrderID    int64                   `json:"order_id"`
	Submitted  *SubmittedConfiguration `json:"submitted"`
	Provenance *ResultProvenance       `json:"provenance"`
	Outcome    ResultOutcome           `json:"outcome"`
	Timing     ResultTiming            `json:"timing"`
	Cost       *RunCost                `json:"cost"`
}

RunDetail is independent of output size. Unknown actual times and exit codes remain null; a reservation is never described as observed execution.

type RunExecution 

type RunExecution struct {
	TimeSource         string     `json:"time_source"`
	StartedObservedAt  *time.Time `json:"started_observed_at"`
	TerminalObservedAt *time.Time `json:"terminal_observed_at"`
	ReportedExitCode   *int32     `json:"reported_exit_code"`
	TCPListener        *string    `json:"tcp_listener"`
	ListenerReady      bool       `json:"listener_ready"`
}

RunExecution records received executor reports using the dispatcher's clock. It does not assert an exact executor start time or network reachability.

type State 

type State struct {
	State      string `json:"state"`
	Error      string `json:"error"`
	ExecutorID string `json:"executor_id"`
}

State is a debuglet's reported state. Unknown state strings are preserved.

type SubmittedConfiguration 

type SubmittedConfiguration struct {
	Label          string   `json:"label"`
	ProgramName    string   `json:"program_name"`
	RequestedStart *int64   `json:"requested_start"`
	Args           []string `json:"args"`
	Policy         Policy   `json:"policy"`
}

SubmittedConfiguration retains the exact requested settings before policy normalization. Program bytes and payment credentials are never copied here.

type TaggingMode 

type TaggingMode struct {
	IPv4  string `json:"ipv4"`
	IPv6  string `json:"ipv6"`
	SCION string `json:"scion"`
	// TagSpec is the packet-tag specification the tagged families follow,
	// TagSpecV1 from this build on (docs/tag-spec.md). Empty, and absent from
	// JSON, is unknown: an executor or dispatcher that predates it. Readers
	// must tolerate values they do not know.
	TagSpec string `json:"tag_spec,omitempty"`
}

TaggingMode is the executor's report of how a run's packets are tagged, per address family and for SCION. It is the node's capability, the mode a run on it is set up to get, not the mode of any particular run; an executor claim, not a verification. Readers must tolerate values they do not know.

type TemplateArgument 

type TemplateArgument struct {
	Type        string `json:"type"`
	Description string `json:"description"`
	Default     string `json:"default"`
}

type TemplateArguments 

type TemplateArguments struct {
	Type                 string                      `json:"type"`
	Properties           map[string]TemplateArgument `json:"properties"`
	Required             []string                    `json:"required"`
	AdditionalProperties bool                        `json:"additionalProperties"`
}

TemplateArguments is a JSON Schema object for the template's input fields. Defaults include only reusable values; destinations require user input.

type TemplateReference 

type TemplateReference struct {
	ID      string `json:"id"`
	Version int    `json:"version"`
}

type User 

type User struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// Role reports the account's permissions; it is not a credential.
	Role string `json:"role"`
	// Economics is reported by API 1.15 and later; it is nil from an older
	// dispatcher.
	Economics *Economics `json:"economics,omitempty"`
}

User is the account a request authenticated as, as reported by GET me.

type VantageCapabilities 

type VantageCapabilities struct {
	Value      *CapabilityReport `json:"value"`
	Source     *string           `json:"source"`
	ObservedAt *time.Time        `json:"observed_at"`
	Stale      *bool             `json:"stale"`
}

VantageCapabilities keeps the last validated capability report even when it had outlived its lifetime at admission; Stale says so. ObservedAt is the dispatcher's receipt time of that report.

type VantagePoint 

type VantagePoint struct {
	ReportedSourceIP *LabelledString     `json:"reported_source_ip,omitempty"`
	Connectivity     *Connectivity       `json:"connectivity,omitempty"`
	SchemaVersion    int                 `json:"schema_version"`
	IPMetadata       *IPMetadata         `json:"ip_metadata,omitempty"`
	Capabilities     VantageCapabilities `json:"capabilities"`
	SourceIP         LabelledString      `json:"source_ip"`
	PublicHost       LabelledString      `json:"public_host"`
	// Added within schema 1; absent in earlier 1.1 files, which means null.
	SCIONISDAS LabelledObservation `json:"scion_isd_as"`
	Display    ExecutorDisplay     `json:"display"`
	// Added within schema 1 with the executor probes; absent means null.
	// Platform is host detail, recorded here because a result is visible only
	// to the run's owner and operators.
	Clock    LabelledReport[ClockReport]  `json:"clock"`
	Platform LabelledReport[HostPlatform] `json:"platform"`
	// Addressing is the RIPE Atlas-style addressing at admission, with the
	// addresses of a private executor too. Added within schema 1; absent in
	// earlier files, which means null.
	Addressing *ProbeAddressing `json:"addressing,omitempty"`
}

VantagePoint is the admission-time view of where a run executes. It carries its own schema version so later facts (ASN, geolocation, reachability) are additive. A value that was not recorded is null together with its source.

type Version 

type Version struct {
	Version         string   `json:"version"`
	APIVersion      string   `json:"api_version"`
	APIVersions     []string `json:"api_versions"`
	BinaryVersion   string   `json:"binary_version"`
	BinaryRevision  string   `json:"binary_revision"`
	ProtocolVersion string   `json:"protocol_version"`
}

Version reports a dispatcher's version identities. Version is the configured string retained from before the HTTP contract was versioned. APIVersion is the HTTP contract served, APIVersions lists its supported major versions, BinaryVersion and BinaryRevision identify the build, and ProtocolVersion is the executor control protocol. Every field beyond Version is empty for older dispatchers; current dispatchers omit an empty BinaryRevision.

Source Files

View all Source files

Directories

Path Synopsis
Package experiment contains readiness data shared by hosts and guests without dependencies on host protocol implementations.
 Package experiment contains readiness data shared by hosts and guests without dependencies on host protocol implementations.

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.