Documentation
¶
Overview ¶
Package client provides the public, run-oriented r1s client API.
A Client is an ephemeral RNS participant and controls one logical run in its lifetime. It does not persist requests, identities, or lease intent. The authenticated RNS identity owned by the Client is the authority for every execution attempt it creates. A caller may either open joined credentials directly or use the local cluster-authority broker selected by `cluster use`.
Index ¶
- Variables
- type Attempt
- type Client
- func (c *Client) Close() []PendingRelease
- func (c *Client) Identity() []byte
- func (c *Client) Inspect(ctx context.Context, executionID string, wait time.Duration) (*r1sv1.ExecutionState, error)
- func (c *Client) Logs(ctx context.Context, executionID, stream string, offset uint64, ...) (*r1sv1.ExecutionLogsResponse, error)
- func (c *Client) NewRunTunnel(targets []TunnelTarget) (*RunTunnel, error)
- func (c *Client) OpenTunnel(ctx context.Context, executionID string, peerKey []byte, ...) (TunnelEndpoint, error)
- func (c *Client) Run(ctx context.Context, request *r1sv1.ExecutionRequest, options RunOptions) (Result, error)
- func (c *Client) Start(ctx context.Context) error
- func (c *Client) Stats() Statistics
- type Config
- type Event
- type EventKind
- type ExecutionSnapshot
- type PendingRelease
- type RequestSnapshot
- type Result
- type RunOptions
- type RunTunnel
- type Statistics
- type Stream
- type TunnelEndpoint
- type TunnelTarget
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrClosed is returned after the client has been closed. ErrClosed = errors.New("r1s client is closed") // ErrNotStarted is returned when Run is called before Start. ErrNotStarted = errors.New("r1s client is not started") // ErrRunActive is returned when the same ephemeral client is asked to own a // second logical run. Construct a fresh Client to get fresh run authority. ErrRunActive = errors.New("r1s client already controls or controlled a run") )
var ( // ErrNoActiveExecution is returned when Dial is called before SetActive. ErrNoActiveExecution = errors.New("run tunnel has no active execution") // ErrTunnelTargetNotAllowed is returned when Dial names a container port // that was not declared when the RunTunnel was created. ErrTunnelTargetNotAllowed = errors.New("run tunnel target port is not allowed") // ErrRunTunnelClosed is returned after a RunTunnel has been closed. ErrRunTunnelClosed = errors.New("run tunnel is closed") // ErrRunTunnelActive is returned when a Client is asked to own a second // live RunTunnel for its one logical run. ErrRunTunnelActive = errors.New("r1s client already owns a run tunnel") )
Functions ¶
This section is empty.
Types ¶
type Attempt ¶
type Attempt struct {
RunID string
Number uint64
RequestID string
ExecutionID string
Allocator []byte
}
Attempt identifies one immutable execution attempt of a logical run.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an ephemeral RNS run controller. It is safe for concurrent log reads and event callbacks while Run is active, but intentionally accepts only one Run call in its lifetime so one instance has the same authority boundary as one r1s run process.
func Open ¶
Open resolves a locally joined cluster ID (or unique prefix) and constructs an ephemeral Client. The returned Client still needs Start before Run.
func OpenCurrent ¶
OpenCurrent constructs a Client through the authority broker selected by `r1s cluster use`. The broker retains the cluster key and creates a fresh RNS identity for this Client; run state and lifecycle remain in this process.
func (*Client) Close ¶
func (c *Client) Close() []PendingRelease
Close stops every run tunnel and the control endpoint. Any execution continues until its allocator-side lease expires; transport connection state never determines its lifetime. The returned slice reports offer releases that could not be delivered before shutdown and will therefore fall back to allocator-side offer expiry.
func (*Client) Identity ¶
Identity returns the authenticated RNS identity hash used as execution authority for this client's lifetime.
func (*Client) Inspect ¶
func (c *Client) Inspect(ctx context.Context, executionID string, wait time.Duration) (*r1sv1.ExecutionState, error)
Inspect performs an explicit authenticated state read.
func (*Client) Logs ¶
func (c *Client) Logs(ctx context.Context, executionID, stream string, offset uint64, maxBytes uint32, wait time.Duration) (*r1sv1.ExecutionLogsResponse, error)
Logs performs one explicit, bounded, authenticated allocator-local log read. It is never called implicitly by Run, inspection, completion, or recovery.
func (*Client) NewRunTunnel ¶
func (c *Client) NewRunTunnel(targets []TunnelTarget) (*RunTunnel, error)
NewRunTunnel creates the Client's logical-run-owned tunnel for a fixed set of allowed container ports. Transport resources are created lazily by the first Dial. Close the current RunTunnel before creating another one.
func (*Client) OpenTunnel ¶
func (c *Client) OpenTunnel(ctx context.Context, executionID string, peerKey []byte, targets []TunnelTarget) (TunnelEndpoint, error)
OpenTunnel explicitly asks the selected allocator to authorize peerKey for the given container ports. It performs only the authenticated control-plane operation; the caller chooses and owns the application-data transport.
func (*Client) Run ¶
func (c *Client) Run(ctx context.Context, request *r1sv1.ExecutionRequest, options RunOptions) (Result, error)
Run publishes demand, selects and assigns an allocator, holds the renewable lease, and reschedules only after authenticated conclusive loss. It blocks until the workload reaches a terminal state or ctx ends. Canceling ctx sends a best-effort authenticated execution cancellation before returning.
Example ¶
package main
import (
"context"
"log"
r1sv1 "github.com/mytecor/r1s/api/gen/r1s/v1"
"github.com/mytecor/r1s/client"
)
func main() {
ctx := context.Background()
controller, err := client.Open("0123456789ab", client.Config{})
if err != nil {
log.Fatal(err)
}
defer controller.Close()
if err := controller.Start(ctx); err != nil {
log.Fatal(err)
}
result, err := controller.Run(ctx, &r1sv1.ExecutionRequest{
Workload: &r1sv1.Workload{Image: "registry.example/image@sha256:..."},
Policy: &r1sv1.ExecutionPolicy{},
ResourceClass: "default",
}, client.RunOptions{})
if err != nil {
log.Fatal(err)
}
_, _ = result.ExitStatus()
}
Output:
func (*Client) Start ¶
Start activates the ephemeral endpoint, directly or through the current authority broker. The supplied context bounds the complete client lifetime.
func (*Client) Stats ¶
func (c *Client) Stats() Statistics
Stats returns a snapshot of in-memory requests and executions tracked by this controller.
type Config ¶
type Config struct {
// ClusterKey is the 32-byte cluster membership secret used by New. It is
// used for RNS link authentication and is never included in workload or
// protocol data. OpenCurrent ignores it because the broker retains the key.
ClusterKey []byte
// NetworkWait bounds RNS path discovery, link establishment, and sends.
// Zero uses 30 seconds.
NetworkWait time.Duration
// BrokerAddress overrides the local cluster-authority endpoint used by
// OpenCurrent. Empty uses the platform default (or R1S_SOCKET).
BrokerAddress string
// BootstrapDestinations are public 16-byte RNS destination hashes tried
// immediately for the first request. They grant no realm authority.
BootstrapDestinations []string
}
Config configures an ephemeral run controller.
type Event ¶
Event reports progress without transferring workload stdout or stderr. Logs remain available only through an explicit Logs call.
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 ¶
PendingRelease describes an offer release that will instead be reclaimed by allocator-side expiry after the client shuts down.
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.
type Result ¶
type Result struct {
Attempt Attempt
State *r1sv1.ExecutionState
}
Result is the terminal result of the final execution attempt.
func (Result) ExitStatus ¶
ExitStatus reports the workload exit status when the allocator supplied one.
type RunOptions ¶
type RunOptions struct {
// OfferWait is the discovery and offer-collection window for every attempt.
// Zero uses 10 seconds.
OfferWait time.Duration
// LeaseDuration is the allocator-side lease requested and renewed by this
// controller. Zero uses the protocol default.
LeaseDuration time.Duration
// OnEvent is called synchronously as the run is assigned, rescheduled, or
// encounters an inconclusive renewal error. Callbacks must return promptly.
OnEvent func(Event)
}
RunOptions configures one logical run.
type RunTunnel ¶
type RunTunnel struct {
// contains filtered or unexported fields
}
RunTunnel owns the data-plane side of a logical run's tunnel. The active execution may change across attempts, while each established stream stays bound to the attempt on which it was opened.
Example ¶
package main
import (
"context"
"log"
r1sv1 "github.com/mytecor/r1s/api/gen/r1s/v1"
"github.com/mytecor/r1s/client"
)
func main() {
ctx := context.Background()
controller, err := client.OpenCurrent(client.Config{})
if err != nil {
log.Fatal(err)
}
defer controller.Close()
if err := controller.Start(ctx); err != nil {
log.Fatal(err)
}
runTunnel, err := controller.NewRunTunnel([]client.TunnelTarget{{Port: 9000}})
if err != nil {
log.Fatal(err)
}
defer runTunnel.Close()
_, _ = controller.Run(ctx, &r1sv1.ExecutionRequest{
Workload: &r1sv1.Workload{Image: "registry.example/image@sha256:..."},
Policy: &r1sv1.ExecutionPolicy{},
ResourceClass: "default",
}, client.RunOptions{OnEvent: func(event client.Event) {
if event.Kind == client.EventAttemptAssigned {
runTunnel.SetActive(event.Attempt.ExecutionID)
go func() {
stream, err := runTunnel.Dial(ctx, 9000)
if err != nil {
return
}
defer stream.Close()
// Speak any application protocol over stream.
}()
}
}})
}
Output:
func (*RunTunnel) Close ¶
Close closes the active pair and lazy client edge. It is safe to call more than once; subsequent Dial calls return ErrRunTunnelClosed.
type Statistics ¶
type Statistics struct {
Requests []RequestSnapshot
Executions []ExecutionSnapshot
}
Statistics contains an in-memory snapshot of this client run controller's activity.
type Stream ¶
type Stream interface {
io.ReadWriteCloser
CloseRead() error
CloseWrite() error
}
Stream is a reliable, ordered, bidirectional byte stream to one container port of the active execution attempt. It remains bound to that attempt and ends when its tunnel pair is closed; it is never rerouted after SetActive.
type TunnelEndpoint ¶
TunnelEndpoint is the allocator tunnel edge returned by an authenticated owner-open request.
type TunnelTarget ¶
type TunnelTarget struct {
Port uint16
}
TunnelTarget is a container port authorized for a run-owned tunnel session.