Documentation
¶
Overview ¶
Package client implements transport-independent request, selection, and execution tracking.
Index ¶
- Variables
- func RemoteFailure(e *r1sv1.Envelope) error
- type Allocator
- type Client
- func (o *Client) AllocatorDestinations(resourceClass string, constraints *r1sv1.PlacementConstraints) []string
- func (o *Client) Cancel(executionID, reason string) (string, *r1sv1.Envelope, error)
- func (o *Client) CreateNextAttempt(previous *r1sv1.ExecutionRequest) (string, *r1sv1.Envelope, error)
- func (o *Client) CreateRequest(workload *r1sv1.Workload, policy *r1sv1.ExecutionPolicy, resourceClass string) (string, *r1sv1.Envelope, error)
- func (o *Client) CreateRequestWithConstraints(workload *r1sv1.Workload, policy *r1sv1.ExecutionPolicy, resourceClass string, ...) (string, *r1sv1.Envelope, error)
- func (o *Client) DueLeaseRenewals() []string
- func (o *Client) Execution(executionID string) (ExecutionSnapshot, bool)
- func (o *Client) Executions() []ExecutionSnapshot
- func (o *Client) Handle(_ context.Context, envelope *r1sv1.Envelope) error
- func (o *Client) Inspect(executionID string) (string, *r1sv1.Envelope, error)
- func (o *Client) LeaseDue(executionID string) bool
- func (o *Client) LeaseIntentAllocators(executionID string) []string
- func (o *Client) LeaseIntentLost(executionID string) bool
- func (o *Client) Logs(id, stream string, offset uint64, limit uint32) (string, *r1sv1.Envelope, error)
- func (o *Client) LostLeaseIntents() []string
- func (o *Client) Maintain(executionID string, leaseDuration time.Duration) (destination string, envelope *r1sv1.Envelope, lost bool, err error)
- func (o *Client) PendingReleases() []PendingRelease
- func (o *Client) RebindLeaseIntent(oldExecutionID, newExecutionID string) error
- func (o *Client) RecordLeaseIntent(executionID string, leaseDuration time.Duration, allocators []string) error
- func (o *Client) RegisterAllocator(candidate Allocator) error
- func (o *Client) RequestEnvelope(requestID string) (*r1sv1.Envelope, bool)
- func (o *Client) RequestForExecution(executionID string) (*r1sv1.ExecutionRequest, bool)
- func (o *Client) Requests() []RequestSnapshot
- func (o *Client) Select(requestID string) (string, *r1sv1.Envelope, error)
- func (o *Client) StartOfferReleases(parent context.Context, ...) func() []PendingRelease
- func (o *Client) TunnelOpen(executionID string, peerKey []byte, targets []tunnel.Target) (string, *r1sv1.Envelope, error)
- type Config
- type ExecutionSnapshot
- type PendingRelease
- type RemoteError
- type RequestSnapshot
Constants ¶
This section is empty.
Variables ¶
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") )
Functions ¶
func RemoteFailure ¶ added in v0.1.1
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 (*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) 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
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 ¶
Handle accepts observations from an authenticated allocator and routes each wire payload to the in-memory state transition that owns it.
func (*Client) Inspect ¶
Inspect creates a fresh query so allocator replay caching cannot return stale state.
func (*Client) LeaseDue ¶ added in v0.2.1
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
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
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
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
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 ¶
RegisterAllocator records a verified discovery or authenticated session route.
func (*Client) RequestEnvelope ¶
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 ¶
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 ¶
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
PendingRelease is a stable in-memory command for one unselected allocator.
type RemoteError ¶ added in v0.1.1
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.