client

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 4, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package client implements transport-independent request, selection, and execution tracking.

Index

Constants

This section is empty.

Variables

View Source
var (
	ErrInvalidConfig      = errors.New("invalid client configuration")
	ErrInvalidAllocator   = errors.New("invalid allocator")
	ErrUnsupportedMessage = errors.New("unsupported client message")
	ErrRequestNotFound    = errors.New("request not found")
	ErrExecutionNotFound  = errors.New("execution not found")
	ErrNoOffer            = errors.New("no usable offer")
	ErrConflict           = errors.New("client state conflict")
	ErrUnauthorized       = errors.New("unauthorized allocator")
)

Functions

func RemoteFailure added in v0.1.1

func RemoteFailure(e *r1sv1.Envelope) error

Types

type Allocator

type Allocator struct {
	Identity    []byte
	Destination string
	Hops        uint8
	Capacity    map[string]uint32
	Node        *r1sv1.NodeCapabilities
	// Tunnel endpoint advertisement: the allocator's advertised tunnel edge
	// (the F22-06 Yggdrasil edge host/port plus its destination hash) that a
	// client dials to open a tunnel. Populated from the authenticated announce
	// descriptor; advisory, like Node, and re-discovered on the next announce.
	// Holds empty values when the allocator runs no tunnel edge.
	TunnelHost        string
	TunnelPort        int
	TunnelDestination string
}

Allocator describes a discovered allocator and the route used to reach it. Node is the allocator's advertised capability metadata (nil when the source did not advertise any); it is advisory and revalidated by the allocator at assignment, so a stale client-side copy never grants placement that local policy denies.

type Client

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

Client owns request selection and observed execution state in memory for the lifetime of one run process (F22). There is no durable client snapshot: a restart of the client never resumes a run, and the allocator retains the execution database.

func New

func New(config Config) (*Client, error)

New constructs client state. There is no restoration from durable storage.

func (*Client) AllocatorDestinations added in v0.4.0

func (o *Client) AllocatorDestinations(resourceClass string, constraints *r1sv1.PlacementConstraints) []string

AllocatorDestinations returns every currently known allocator that may satisfy the resource class and placement constraints. The sorted result is discovery state, not pinning: a fresh attempt remains free to select any allocator that offers, including later discoveries.

func (*Client) Cancel

func (o *Client) Cancel(executionID, reason string) (string, *r1sv1.Envelope, error)

Cancel records a stable cancellation before it is sent.

func (*Client) CreateNextAttempt added in v0.4.0

func (o *Client) CreateNextAttempt(previous *r1sv1.ExecutionRequest) (string, *r1sv1.Envelope, error)

CreateNextAttempt creates a fresh request for the next at-least-once attempt of the same logical run. The request and eventual execution IDs are new; only the correlation ID is retained and the attempt number is advanced.

func (*Client) CreateRequest

func (o *Client) CreateRequest(workload *r1sv1.Workload, policy *r1sv1.ExecutionPolicy, resourceClass string) (string, *r1sv1.Envelope, error)

CreateRequest records a request in memory before it is sent to any allocator. It creates an any-node request with no placement constraints.

func (*Client) CreateRequestWithConstraints added in v0.3.1

func (o *Client) CreateRequestWithConstraints(workload *r1sv1.Workload, policy *r1sv1.ExecutionPolicy, resourceClass string, constraints *r1sv1.PlacementConstraints) (string, *r1sv1.Envelope, error)

CreateRequestWithConstraints records a request with placement constraints. The constraints are validated and become part of the stable in-memory request, so every allocator receives the same narrowing on re-request.

func (*Client) DueLeaseRenewals added in v0.2.1

func (o *Client) DueLeaseRenewals() []string

DueLeaseRenewals returns execution IDs whose recorded lease intent is due for renewal: non-terminal, not lost, and past one third of the lease since the last renewal attempt. Callers send each renewal through Maintain.

func (*Client) Execution

func (o *Client) Execution(executionID string) (ExecutionSnapshot, bool)

Execution returns a cloned execution snapshot.

func (*Client) Executions

func (o *Client) Executions() []ExecutionSnapshot

Executions returns stable, sorted execution snapshots.

func (*Client) Handle

func (o *Client) Handle(_ context.Context, envelope *r1sv1.Envelope) error

Handle accepts observations from an authenticated allocator and routes each wire payload to the in-memory state transition that owns it.

func (*Client) Inspect

func (o *Client) Inspect(executionID string) (string, *r1sv1.Envelope, error)

Inspect creates a fresh query so allocator replay caching cannot return stale state.

func (*Client) LeaseDue added in v0.2.1

func (o *Client) LeaseDue(executionID string) bool

LeaseDue reports whether the recorded intent for one execution is due for renewal: non-terminal, not lost, and past one third of the lease since the last renewal attempt.

func (*Client) LeaseIntentAllocators added in v0.2.1

func (o *Client) LeaseIntentAllocators(executionID string) []string

LeaseIntentAllocators returns the allocator destinations recorded with the lease-holding intent of one execution, so a re-request after lease loss can preserve the original pinning.

func (*Client) LeaseIntentLost added in v0.2.1

func (o *Client) LeaseIntentLost(executionID string) bool

LeaseIntentLost reports whether an execution's lease expired before a renewal landed, so its recorded workload must be re-requested.

func (*Client) Logs added in v0.1.1

func (o *Client) Logs(id, stream string, offset uint64, limit uint32) (string, *r1sv1.Envelope, error)

Logs creates one explicit request. Intent is transient; restart never resumes it.

func (*Client) LostLeaseIntents added in v0.2.1

func (o *Client) LostLeaseIntents() []string

LostLeaseIntents returns execution IDs whose lease expired before a renewal landed. Their recorded workload must be re-requested.

func (*Client) Maintain added in v0.2.1

func (o *Client) Maintain(executionID string, leaseDuration time.Duration) (destination string, envelope *r1sv1.Envelope, lost bool, err error)

Maintain records the in-memory lease-holding intent for one execution and returns a one-shot authenticated renewal command. The public run controller replays this intent on every tick. Maintain never spawns a background process.

lost=true reports that the execution's lease already expired without renewal (the execution was evicted or its metadata is gone): the recorded workload must be re-requested with a fresh request, and the intent then rebinds to the replacement execution via RebindLeaseIntent.

func (*Client) PendingReleases added in v0.1.1

func (o *Client) PendingReleases() []PendingRelease

PendingReleases returns independent envelopes until acknowledged or expired. Sending is best-effort; expiry is always the allocator's cleanup fallback.

func (*Client) RebindLeaseIntent added in v0.2.1

func (o *Client) RebindLeaseIntent(oldExecutionID, newExecutionID string) error

RebindLeaseIntent moves a lost lease-holding intent to a replacement execution created by re-requesting the recorded workload, carrying the recorded allocator pinning along.

func (*Client) RecordLeaseIntent added in v0.2.1

func (o *Client) RecordLeaseIntent(executionID string, leaseDuration time.Duration, allocators []string) error

RecordLeaseIntent records the in-memory lease-holding intent for one execution without sending anything. The public run controller replays it on every tick and renews when due. Explicit allocator destinations ride with the intent so a re-request after lease loss preserves the original pinning.

func (*Client) RegisterAllocator

func (o *Client) RegisterAllocator(candidate Allocator) error

RegisterAllocator records a verified discovery or authenticated session route.

func (*Client) RequestEnvelope

func (o *Client) RequestEnvelope(requestID string) (*r1sv1.Envelope, bool)

RequestEnvelope returns the stable request envelope used for all allocators.

func (*Client) RequestForExecution added in v0.2.1

func (o *Client) RequestForExecution(executionID string) (*r1sv1.ExecutionRequest, bool)

RequestForExecution returns the recorded workload request backing one execution, so a re-request after lease loss can replay it verbatim.

func (*Client) Requests

func (o *Client) Requests() []RequestSnapshot

Requests returns stable, sorted snapshots.

func (*Client) Select

func (o *Client) Select(requestID string) (string, *r1sv1.Envelope, error)

Select asks the route catalog to rank live offers, then atomically records both the chosen assignment and release intents for every losing offer.

func (*Client) StartOfferReleases added in v0.1.1

func (o *Client) StartOfferReleases(parent context.Context, send func(context.Context, string, *r1sv1.Envelope) error) func() []PendingRelease

StartOfferReleases retries in-memory offer cleanup without blocking assignment or state handling. The run controller retries the stable pending set, including late offers. Shutdown gives ACKs a bounded window; an unreachable allocator still has its original lease expiry.

func (*Client) TunnelOpen added in v0.4.0

func (o *Client) TunnelOpen(executionID string, peerKey []byte, targets []tunnel.Target) (string, *r1sv1.Envelope, error)

TunnelOpen creates a fresh declaration of the owned run's tunnel binding for an execution (F22-06): it pins the client's edge node public key and the client-supplied destination container port list to the execution over the authenticated control plane. There is no transient grant token: the binding lives for the execution's lifetime, nothing is persisted (after an allocator restart the run simply re-declares), and the allocator authorizes a tunnel mesh peer that presents the bound key directly. Targets is the client-owned slot list the allocator binds to the execution; at least one destination is required.

type Config

type Config struct {
	Identity []byte
	Now      func() time.Time
	NewID    func() string
}

Config defines local client authority. Since F22-07 the client is an ephemeral, in-memory run process: there is no persistent store, durable identity, or durable lease intent, so Config carries only the authenticated authority and its time/ID sources.

type ExecutionSnapshot

type ExecutionSnapshot struct {
	ExecutionID string
	RequestID   string
	OfferID     string
	Allocator   []byte
	Destination string
	State       *r1sv1.ExecutionState
}

ExecutionSnapshot is a read-only view of a client execution.

type PendingRelease added in v0.1.1

type PendingRelease struct {
	Destination string
	Envelope    *r1sv1.Envelope
}

PendingRelease is a stable in-memory command for one unselected allocator.

type RemoteError added in v0.1.1

type RemoteError struct {
	Code, Detail string
	Retryable    bool
}

func (*RemoteError) Error added in v0.1.1

func (e *RemoteError) Error() string

type RequestSnapshot

type RequestSnapshot struct {
	Request     *r1sv1.ExecutionRequest
	CreatedAt   time.Time
	OfferCount  int
	ExecutionID string
}

RequestSnapshot is a read-only view of a client request.

Jump to

Keyboard shortcuts

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