Help us shape the future of Go! Take the 2026 Go Developer Survey

targetsession

package
v0.4.26 Latest Latest
Warning

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

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

Documentation

Overview

Package targetsession transports already selected Core operations. It does not choose placement, authorize actors or invoke a local runtime fallback.

Index

Constants

This section is empty.

Variables

View Source 
var ErrUnavailable = errors.New("authenticated Connector session is unavailable; reconcile before retrying a mutation")

Functions

func WithPool 

func WithPool(ctx context.Context, pool *Pool) context.Context

Types

type Capabilities 

type Capabilities struct {
	ContractVersion string       `json:"contract_version"`
	ProtocolVersion string       `json:"protocol_version"`
	Node            Node         `json:"node"`
	Capabilities    []Capability `json:"capabilities"`
}

type Capability 

type Capability struct {
	Name      string `json:"name"`
	Available bool   `json:"available"`
	Detail    string `json:"detail,omitempty"`
}

type LogOptions 

type LogOptions struct {
	Tail   int    `json:"tail,omitempty"`
	Since  string `json:"since,omitempty"`
	Follow bool   `json:"follow,omitempty"`
}

type Node 

type Node struct {
	TenantID   string `json:"tenant_id"`
	NodeID     string `json:"node_id"`
	TargetID   string `json:"target_id"`
	Runtime    string `json:"runtime"`
	Identity   string `json:"identity"`
	InstanceID string `json:"instance_id,omitempty"`
}

func (Node) Scope 

func (n Node) Scope() targetenrollment.Scope

type NodeMemoryEvidence 

type NodeMemoryEvidence struct {
	TotalBytes     uint64
	AvailableBytes uint64
	SwapTotalBytes uint64
	SwapFreeBytes  uint64
}

type Pool 

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

Pool is indexed by the exact enrolled scope. It never retries an invocation on a different connection and never resolves an unavailable remote locally.

func NewPool 

func NewPool() *Pool

func PoolFromContext 

func PoolFromContext(ctx context.Context) *Pool

func (*Pool) Dispatch 

func (p *Pool) Dispatch(ctx context.Context, scope targetenrollment.Scope, request Request) (Response, error)

func (*Pool) LiveCapabilities 

func (p *Pool) LiveCapabilities(scope targetenrollment.Scope) (Capabilities, error)

func (*Pool) OpenStream 

func (p *Pool) OpenStream(ctx context.Context, scope targetenrollment.Scope, open StreamOpen) (*Stream, error)

func (*Pool) Serve 

func (p *Pool) Serve(ctx context.Context, listener net.Listener, configuration *tls.Config, registry targetenrollment.NodeRegistry, coreIdentity string) error

Serve admits outbound connections with bounded handshake concurrency and per-scope capacity. Closing the listener or cancelling ctx retires sessions. Configuration and Core identity are validated by the TLS authority caller.

type Problem 

type Problem struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	Retryable bool   `json:"retryable,omitempty"`
}

type ProjectFile 

type ProjectFile struct {
	Path string
	Data []byte
	Mode uint32
}

type ProjectFileRecord 

type ProjectFileRecord struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	Mode   uint32 `json:"mode,omitempty"`
}

type ProjectRecord 

type ProjectRecord struct {
	Version   int                    `json:"version"`
	Scope     targetenrollment.Scope `json:"scope"`
	BundleID  string                 `json:"bundle_id"`
	Directory string                 `json:"directory"`
	Files     []ProjectFileRecord    `json:"files"`
}

ProjectRecord is persisted only in protected, Core-owned deployment state. It contains commitments and relative Node paths, never file/secret contents. It is not an operator API input or independent authority over a project.

func (ProjectRecord) Validate 

func (record ProjectRecord) Validate() error

Validate checks a durable commitment without granting execution authority. Execution still requires the current authorized Scope and exact source bytes.

type ProjectRuntime 

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

ProjectRuntime binds immutable project artifacts to one authenticated node. It never resolves a remote selection locally or replays an interrupted call.

func NewProjectRuntime 

func NewProjectRuntime(transport ProjectTransport, scope targetenrollment.Scope) (*ProjectRuntime, error)

func (*ProjectRuntime) ApplyCompose 

func (r *ProjectRuntime) ApplyCompose(ctx context.Context, project *StagedProject, files []string, envFile string, repair bool) error

func (*ProjectRuntime) ApplyComposeSelected 

func (r *ProjectRuntime) ApplyComposeSelected(ctx context.Context, project *StagedProject, files []string, envFile string, services []string, repair bool) error

ApplyComposeSelected activates only a Core-selected phase of one immutable project. The node disables implicit dependency activation and source builds; Core must explicitly converge and verify prerequisites before the next phase.

func (*ProjectRuntime) ApplyQuadlet 

func (r *ProjectRuntime) ApplyQuadlet(ctx context.Context, project *StagedProject, file string) error

func (*ProjectRuntime) ApplyQuadletGraph 

func (r *ProjectRuntime) ApplyQuadletGraph(ctx context.Context, project *StagedProject, files []string) error

func (*ProjectRuntime) ApplyQuadletInitGraph 

func (r *ProjectRuntime) ApplyQuadletInitGraph(ctx context.Context, project *StagedProject, files, initFiles []string) error

ApplyQuadletInitGraph keeps completion sequencing in Core. The complete graph is published first; an init unit's current source must finish successfully before its dependent can activate. No admitted mutation is retried.

func (*ProjectRuntime) DestroyCompose 

func (r *ProjectRuntime) DestroyCompose(ctx context.Context, project *StagedProject, files []string, envFile string) error

func (*ProjectRuntime) DestroyComposeOwned 

func (r *ProjectRuntime) DestroyComposeOwned(ctx context.Context, project *StagedProject, files []string, envFile string, volumes bool) error

Persistent volumes are removed only for an explicit Core-owned reset.

func (*ProjectRuntime) DestroyQuadlet 

func (r *ProjectRuntime) DestroyQuadlet(ctx context.Context, project *StagedProject, file string) error

func (*ProjectRuntime) DestroyQuadletGraph 

func (r *ProjectRuntime) DestroyQuadletGraph(ctx context.Context, project *StagedProject, files []string) error

DestroyQuadletGraph removes only the selected, receipt-bound units. Provider data volumes remain intact; this is not an implicit destructive reset.

func (*ProjectRuntime) ExecService 

func (r *ProjectRuntime) ExecService(ctx context.Context, project, service string, argv ...string) (string, error)

ExecService executes a Core-approved backend probe in exactly one owned, running service. It re-resolves the immutable container ID for every call; ambiguous replicas, foreign labels and missing exit status fail closed.

func (*ProjectRuntime) NodeMemory 

func (r *ProjectRuntime) NodeMemory(ctx context.Context) (NodeMemoryEvidence, error)

NodeMemory requests fresh execution-node evidence over the same exact authenticated scope as project mutations. Core-host capacity is no fallback.

func (*ProjectRuntime) ObserveProject 

func (r *ProjectRuntime) ObserveProject(ctx context.Context, project string) ([]ProjectService, error)

ObserveProject resolves a Core-selected project through live inventory and independently verifies each container's native ownership labels. Container names never establish ownership, including on rootless Quadlet targets.

func (*ProjectRuntime) PublishQuadletGraph 

func (r *ProjectRuntime) PublishQuadletGraph(ctx context.Context, project *StagedProject, files []string) error

PublishQuadletGraph publishes validated, receipt-bound sources without activating containers. Completion dependencies can be staged before execution.

func (*ProjectRuntime) RemoveOwnedService 

func (r *ProjectRuntime) RemoveOwnedService(ctx context.Context, project, service string, force bool) error

RemoveOwnedService re-resolves ownership immediately before removing one exact native ID. Provider stop time fits the bounded project operation rather than a short probe deadline. A lost response is never replayed.

func (*ProjectRuntime) ResetQuadletGraph 

func (r *ProjectRuntime) ResetQuadletGraph(ctx context.Context, project *StagedProject, files []string) error

ResetQuadletGraph is used only after an explicit Core-owned data reset decision. Validate every selection and live reset capability before teardown.

func (*ProjectRuntime) RestoreProject 

func (r *ProjectRuntime) RestoreProject(record ProjectRecord, files []ProjectFile) (*StagedProject, error)

RestoreProject rebinds a durable Core receipt to the current authorized Scope and exact protected source bytes. It never stages another bundle or retries a mutation. Compose revalidates the immutable Node manifest before execution; Quadlet realization uses these exact revalidated source bytes.

func (*ProjectRuntime) Stage 

func (r *ProjectRuntime) Stage(ctx context.Context, id string, files []ProjectFile) (*StagedProject, error)

func (*ProjectRuntime) VerifyCompletedService 

func (r *ProjectRuntime) VerifyCompletedService(ctx context.Context, project, service string) error

VerifyCompletedService verifies a one-shot through owned native container evidence. Stopped, never-started and missing/removed containers are not proof of success. Quadlet units that remove their container need a separately qualified unit-completion observation; this method never infers it.

func (*ProjectRuntime) VerifyQuadletCompletion 

func (r *ProjectRuntime) VerifyQuadletCompletion(ctx context.Context, project *StagedProject, file string) error

VerifyQuadletCompletion asks the authenticated Node to verify successful execution after activation of this exact immutable source on its current boot. Missing containers or an earlier unit's success cannot substitute for proof. This observation never republishes, starts or retries a runtime mutation.

type ProjectService 

type ProjectService struct {
	ID         string
	Service    string
	Running    bool
	Health     string
	State      string
	ExitCode   *int
	StartedAt  time.Time
	FinishedAt time.Time
}

ProjectService is an observation, not a readiness decision. Backend probes still have to verify the application's actual TLS and service contract.

type ProjectTransport 

type ProjectTransport interface {
	LiveCapabilities(targetenrollment.Scope) (Capabilities, error)
	Dispatch(context.Context, targetenrollment.Scope, Request) (Response, error)
}

ProjectTransport carries already authorized Core realization decisions. It neither selects an Application placement nor authorizes an operator.

type Request 

type Request struct {
	ContractVersion string          `json:"contract_version"`
	ProtocolVersion string          `json:"protocol_version"`
	RequestID       string          `json:"request_id"`
	CorrelationID   string          `json:"correlation_id"`
	TargetID        string          `json:"target_id"`
	Operation       string          `json:"operation"`
	IssuedAt        time.Time       `json:"issued_at"`
	DeadlineAt      time.Time       `json:"deadline_at"`
	Payload         json.RawMessage `json:"payload,omitempty"`
}

Request is the canonical bounded transport projection, not a host command.

type Response 

type Response struct {
	ContractVersion string          `json:"contract_version"`
	ProtocolVersion string          `json:"protocol_version"`
	RequestID       string          `json:"request_id"`
	CorrelationID   string          `json:"correlation_id"`
	Success         bool            `json:"success"`
	Result          json.RawMessage `json:"result,omitempty"`
	Error           *Problem        `json:"error,omitempty"`
}

type Session 

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

Session has one bounded control request in flight. Failed or cancelled dispatch always retires the connection; a side effect is never auto-replayed.

func Accept 

func Accept(ctx context.Context, conn *tls.Conn, registry targetenrollment.NodeRegistry, coreIdentity string) (*Session, error)

Accept exchanges the canonical Hello only after a verified TLS 1.3 handshake. The caller configures RequireAndVerifyClientCert and a trusted Core server certificate. coreIdentity must be that certificate's sole SPIFFE URI.

func (*Session) Close 

func (s *Session) Close() error

func (*Session) Dispatch 

func (s *Session) Dispatch(ctx context.Context, request Request) (Response, error)

func (*Session) LiveCapabilities 

func (s *Session) LiveCapabilities() (Capabilities, error)

LiveCapabilities returns a copy of the authenticated negotiation, never the provider descriptor. Unavailable sessions advertise no live capability.

func (*Session) OpenStream 

func (s *Session) OpenStream(ctx context.Context, open StreamOpen) (*Stream, error)

func (*Session) Scope 

func (s *Session) Scope() targetenrollment.Scope

type StagedProject 

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

StagedProject can only be constructed after validating the remote staging receipt. Its scope, paths and bytes cannot be substituted by a caller.

func (*StagedProject) Record 

func (p *StagedProject) Record() ProjectRecord

type Stream 

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

Stream exclusively owns a session and retires it on every outcome. A pipe applies backpressure without buffering unbounded peer output. Interactive processes are never resumed or transparently moved to another connection.

func (*Stream) Close 

func (s *Stream) Close() error

func (*Stream) Read 

func (s *Stream) Read(data []byte) (int, error)

func (*Stream) Resize 

func (s *Stream) Resize(rows, cols int) error

func (*Stream) Wait 

func (s *Stream) Wait(ctx context.Context) (int, error)

func (*Stream) Write 

func (s *Stream) Write(data []byte) (int, error)

type StreamOpen 

type StreamOpen struct {
	ContractVersion string           `json:"contract_version"`
	ProtocolVersion string           `json:"protocol_version"`
	StreamID        string           `json:"stream_id"`
	CorrelationID   string           `json:"correlation_id"`
	TargetID        string           `json:"target_id"`
	ResourceID      string           `json:"resource_id"`
	Kind            string           `json:"kind"`
	DeadlineAt      time.Time        `json:"deadline_at"`
	Logs            *LogOptions      `json:"logs,omitempty"`
	Terminal        *TerminalOptions `json:"terminal,omitempty"`
}

type TerminalOptions 

type TerminalOptions struct {
	Rows int      `json:"rows"`
	Cols int      `json:"cols"`
	Argv []string `json:"argv"`
}

Source Files

View all Source files

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.