core

package
v1.0.0-alpha.1 Latest Latest
Warning

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

 Go to latest Published: Sep 28, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package core owns Wire's logical resource lifetimes and protocol-neutral operations.

Index

Constants

This section is empty.

Variables

View Source 
var ErrWatcherLagged = errors.New("wire watcher lagged")

ErrWatcherLagged reports that a bounded subscription could not retain an event.

Functions

func DiagnosticsFromError 

func DiagnosticsFromError(err error) diagnostics.Diagnostics

DiagnosticsFromError extracts and detaches only canonical diagnostics from an error chain.

func OperationContext 

func OperationContext(parent, lifetime context.Context) (context.Context, context.CancelFunc)

OperationContext preserves request values and deadlines while joining the resource lifetime. Call cancel to detach the lifetime cancellation callback.

Types

type Connection 

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

Connection is the logical identity and lifetime established by the Connect stream. Its store owns allocation and reclamation within this lifetime.

func (*Connection) Context 

func (c *Connection) Context() context.Context

Context is cancelled when logical connection teardown begins.

func (*Connection) ID 

func (c *Connection) ID() ConnectionID

ID identifies this logical connection independently of its physical transport.

func (*Connection) Resources 

func (c *Connection) Resources() *ResourceStore

Resources returns the store owned by this logical connection.

type ConnectionID 

type ConnectionID string

ConnectionID is the opaque registry key for a logical connection.

type ConnectionRegistry 

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

ConnectionRegistry owns the global logical-connection index and capacity.

func NewConnectionRegistry 

func NewConnectionRegistry(maxConnections int, limits ResourceLimits) *ConnectionRegistry

NewConnectionRegistry sets connection capacity and the limits inherited by each connection.

func (*ConnectionRegistry) Close 

func (r *ConnectionRegistry) Close(ctx context.Context) error

Close rejects new connections and starts teardown of all retained connections. The caller's context bounds waiting, not ownership of teardown.

func (*ConnectionRegistry) CloseConnection 

func (r *ConnectionRegistry) CloseConnection(ctx context.Context, id ConnectionID) error

CloseConnection commits teardown once and waits using the caller's context. Teardown continues if that context is cancelled.

func (*ConnectionRegistry) Get 

func (r *ConnectionRegistry) Get(id ConnectionID) (*Connection, error)

Get returns an active connection; closing connections are no longer discoverable.

func (*ConnectionRegistry) Open 

func (r *ConnectionRegistry) Open() (*Connection, error)

Open admits a logical connection unless shutdown or connection capacity prevents it.

type DebugSession 

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

DebugSession owns a hosted debugger, its command state, breakpoints, and event subscriptions.

func (*DebugSession) BreakpointLimit 

func (d *DebugSession) BreakpointLimit() int

BreakpointLimit lets the transport reject oversized batches before allocating their decoded representation. Replacement still validates the resulting set.

func (*DebugSession) Breakpoints 

func (d *DebugSession) Breakpoints(ctx context.Context) ([]debugger.Breakpoint, error)

Breakpoints reads the hosted snapshot, including after hosted Close.

func (*DebugSession) Close 

func (d *DebugSession) Close(ctx context.Context) error

Close stops the hosted debugger once, retaining the logical handle until Release.

func (*DebugSession) Command 

func (d *DebugSession) Command(name string) (func(context.Context) (*debugger.Event, error), error)

Command resolves canonical execution operations without exposing hosted state.

func (*DebugSession) Continue 

func (d *DebugSession) Continue(ctx context.Context) (wiredebugger.Snapshot, error)

Continue resumes a stopped debugger asynchronously and returns its running snapshot.

func (*DebugSession) DeleteBreakpoint 

func (d *DebugSession) DeleteBreakpoint(ctx context.Context, breakpointID debugger.BreakpointID) error

DeleteBreakpoint removes a known breakpoint from a nonterminal debugger.

func (*DebugSession) Done 

func (d *DebugSession) Done() <-chan struct{}

Done closes after hosted debugger cleanup and all admitted commands settle.

func (*DebugSession) Evaluate 

func (d *DebugSession) Evaluate(ctx context.Context, expression string) (debugger.Value, error)

Evaluate invokes the hosted default-frame operation directly.

func (*DebugSession) EvaluateFrame 

func (d *DebugSession) EvaluateFrame(
	ctx context.Context,
	frame int,
	expression string,
) (debugger.Value, error)

EvaluateFrame evaluates an expression in a stopped frame with caller and session cancellation.

func (*DebugSession) FrameLocals 

func (d *DebugSession) FrameLocals(ctx context.Context, frame int) ([]debugger.Variable, error)

FrameLocals reads variables in a nonnegative frame index while the debugger is stopped.

func (*DebugSession) Frames 

func (d *DebugSession) Frames(ctx context.Context) ([]debugger.Frame, error)

Frames returns a detached frame slice while the debugger is stopped.

func (*DebugSession) ID 

func (d *DebugSession) ID() DebugSessionID

ID identifies this debug session within its logical connection.

func (*DebugSession) Locals 

func (d *DebugSession) Locals(ctx context.Context) ([]debugger.Variable, error)

Locals invokes the hosted default-frame operation directly.

func (*DebugSession) Pause 

func (d *DebugSession) Pause(ctx context.Context) (wiredebugger.Snapshot, error)

Pause requests interruption of a running debugger; a later event reports the stop.

func (*DebugSession) Release 

func (d *DebugSession) Release(ctx context.Context) error

Release closes the hosted debugger and removes it from its plan's resource store. Caller cancellation stops waiting without abandoning teardown.

func (*DebugSession) ReplaceBreakpoints 

func (d *DebugSession) ReplaceBreakpoints(ctx context.Context, sourceName string, requests []debugger.BreakpointRequest) ([]debugger.Breakpoint, error)

ReplaceBreakpoints preserves atomic hosted publication and charges the resulting source set, including unresolved requests and breakpoints in other sources.

func (*DebugSession) ReserveCommandStream 

func (d *DebugSession) ReserveCommandStream() (func(), error)

ReserveCommandStream bounds live command receivers, including Start's retained lifetime stream. The extra slot permits a resume with the minimum watch limit. Admission stays charged until the RPC handler exits, even after command completion.

func (*DebugSession) RunCommand 

func (d *DebugSession) RunCommand(ctx context.Context, initial bool, command func(context.Context) (*debugger.Event, error)) (*wiredebugger.CommandResult, error)

RunCommand retains the caller context through the hosted command. The caller keeps a successful Start context alive for the execution's remaining lifetime.

func (*DebugSession) SetBreakpoint 

func (d *DebugSession) SetBreakpoint(
	ctx context.Context,
	location source.Location,
) (debugger.Breakpoint, error)

SetBreakpoint binds to the next executable location in the requested source.

func (*DebugSession) SetBreakpointAt 

func (d *DebugSession) SetBreakpointAt(
	ctx context.Context,
	location source.Location,
	options debugger.BreakpointOptions,
) (debugger.Breakpoint, error)

SetBreakpointAt validates and installs a breakpoint in a nonterminal debugger.

func (*DebugSession) Snapshot 

func (d *DebugSession) Snapshot() wiredebugger.Snapshot

Snapshot returns Wire-visible debugger state detached from mutable session storage.

func (*DebugSession) Start 

func (d *DebugSession) Start(ctx context.Context) (wiredebugger.Snapshot, error)

Start begins a created debugger asynchronously and returns its running snapshot.

func (*DebugSession) StepIn 

func (d *DebugSession) StepIn(ctx context.Context) (wiredebugger.Snapshot, error)

StepIn resumes a stopped debugger with the hosted step-in command.

func (*DebugSession) StepOut 

func (d *DebugSession) StepOut(ctx context.Context) (wiredebugger.Snapshot, error)

StepOut resumes a stopped debugger with the hosted step-out command.

func (*DebugSession) StepOver 

func (d *DebugSession) StepOver(ctx context.Context) (wiredebugger.Snapshot, error)

StepOver resumes a stopped debugger with the hosted step-over command.

func (*DebugSession) Stop 

func (d *DebugSession) Stop(ctx context.Context) (wiredebugger.Snapshot, error)

Stop closes a nonterminal debugger and returns its terminal snapshot.

func (*DebugSession) Variables 

func (d *DebugSession) Variables(
	ctx context.Context,
	reference debugger.ValueReference,
) ([]debugger.Variable, error)

Variables expands a positive value reference while the debugger is stopped.

func (*DebugSession) Watch 

func (d *DebugSession) Watch() (DebugSubscription, error)

Watch reserves a bounded subscription with the current snapshot. The caller must cancel the subscription to release its watcher slot.

type DebugSessionID 

type DebugSessionID string

DebugSessionID is the opaque registry key for a debug session.

type DebugSubscription 

type DebugSubscription struct {
	Current wiredebugger.Event
	Events  <-chan wiredebugger.Event
	Errors  <-chan error
	Cancel  func()
}

DebugSubscription pairs a current snapshot with subsequent ordered events. Cancel releases the watcher slot, including after the event channels close.

type DomainError 

type DomainError struct {
	Kind       ErrorKind
	ResourceID string
	Message    string
	Cause      error
}

DomainError carries a classified failure and its private cause for transport mapping.

func (*DomainError) Category 

func (e *DomainError) Category() failure.Category

Category returns the shared Wire failure category; transport-native conditions have none.

func (*DomainError) Error 

func (e *DomainError) Error() string

func (*DomainError) Unwrap 

func (e *DomainError) Unwrap() error

type ErrorKind 

type ErrorKind uint8

ErrorKind distinguishes lifecycle, input, capacity, and hosted-runtime failures. 

const (
	ErrorKindInvalidRequest ErrorKind = iota + 1
	ErrorKindCompilation
	ErrorKindExecution
	ErrorKindPlanNotFound
	ErrorKindExecutionNotFound
	ErrorKindDebugSessionNotFound
	ErrorKindConnectionNotFound
	ErrorKindInvalidState
	ErrorKindUnsupported
	ErrorKindInternal
	ErrorKindWatcherLagged
	ErrorKindResourceExhausted
	ErrorKindBreakpointNotFound
	ErrorKindSessionNotFound
)

Domain error kinds distinguish Wire conditions before transport-specific mapping.

type Execution 

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

Execution owns one asynchronous run and retains its terminal result until release.

func Run 

func Run(ctx context.Context, runtime api.Runtime, store *ResourceStore, source api.Source, options ...api.SessionOption) (*Execution, error)

Run creates an asynchronous execution of exactly one hosted Runtime.Run call.

func (*Execution) Cancel 

func (e *Execution) Cancel() wireexecution.Snapshot

Cancel requests cancellation and returns the current snapshot without waiting for termination.

func (*Execution) ID 

func (e *Execution) ID() ExecutionID

ID identifies this run within its logical connection.

func (*Execution) Release 

func (e *Execution) Release(ctx context.Context) error

Release cancels and joins the run, closes its event stream, and removes its handle. Caller cancellation stops waiting without abandoning teardown.

func (*Execution) Snapshot 

func (e *Execution) Snapshot() wireexecution.Snapshot

Snapshot returns execution state with mutable output and diagnostics detached.

func (*Execution) Watch 

func (e *Execution) Watch() (ExecutionSubscription, error)

Watch reserves a bounded subscription with the current snapshot. The caller must cancel the subscription to release its watcher slot.

type ExecutionID 

type ExecutionID string

ExecutionID is the opaque registry key for an execution.

type ExecutionSubscription 

type ExecutionSubscription struct {
	Current execution.Event
	Events  <-chan execution.Event
	Errors  <-chan error
	Cancel  func()
}

ExecutionSubscription pairs a current snapshot with subsequent ordered events. Cancel releases the watcher slot, including after the event channels close.

type Plan 

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

Plan owns a compiled hosted plan and the sessions and executions created from it.

func CompilePlan 

func CompilePlan(ctx context.Context, runtime api.Runtime, store *ResourceStore, source api.Source, debug bool, options ...api.PlanOption) (*Plan, error)

CompilePlan creates a connection-owned plan using the borrowed hosted runtime.

func (*Plan) Close 

func (p *Plan) Close(ctx context.Context) error

Close prevents new constructors and closes only the hosted plan. Constructors admitted before Close retain their contexts and may publish caller-owned children.

func (*Plan) Execute 

func (p *Plan) Execute(ctx context.Context, options ...api.SessionOption) (*Execution, error)

Execute registers an asynchronous run using a temporary hosted session.

func (*Plan) ID 

func (p *Plan) ID() PlanID

ID identifies this compiled plan within its logical connection.

func (*Plan) NewDebugSession 

func (p *Plan) NewDebugSession(ctx context.Context, options ...api.SessionOption) (*DebugSession, error)

NewDebugSession creates and registers a hosted debugger for a debuggable plan.

func (*Plan) NewSession 

func (p *Plan) NewSession(ctx context.Context, options ...api.SessionOption) (*Session, error)

NewSession creates and registers a durable hosted session owned by this plan.

func (*Plan) Params 

func (p *Plan) Params() []string

Params returns a copy of the compiled plan's parameter names.

func (*Plan) Release 

func (p *Plan) Release(ctx context.Context) error

Release closes descendants before releasing the hosted plan and its registry entry. Caller cancellation stops waiting without abandoning teardown.

type PlanID 

type PlanID string

PlanID is the opaque registry key for a compiled plan.

type ResourceLimits 

type ResourceLimits struct {
	Plans         int
	Sessions      int
	Executions    int
	DebugSessions int
	Watchers      int
	Breakpoints   int
}

ResourceLimits bounds one logical connection, including pending and closing resources.

type ResourceStore 

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

ResourceStore owns the resources of exactly one logical connection. mu protects membership, reservations, parent links, and release admission. Resource state locks must never be held when acquiring mu. No hosted call or cleanup wait runs under mu.

func (*ResourceStore) Close 

func (r *ResourceStore) Close(ctx context.Context) error

Close rejects new resource creation and starts teardown once. The caller's context bounds waiting while the store retains cleanup ownership.

func (*ResourceStore) DebugSession 

func (r *ResourceStore) DebugSession(ctx context.Context, id DebugSessionID) (*DebugSession, error)

DebugSession resolves a live debugger in this connection and rejects handles being released.

func (*ResourceStore) Execution 

func (r *ResourceStore) Execution(ctx context.Context, id ExecutionID) (*Execution, error)

Execution resolves a live execution in this connection and rejects handles being released.

func (*ResourceStore) Plan 

func (r *ResourceStore) Plan(ctx context.Context, id PlanID) (*Plan, error)

Plan resolves a live plan in this connection and rejects handles being released.

func (*ResourceStore) ReleaseDebugSession 

func (r *ResourceStore) ReleaseDebugSession(ctx context.Context, id DebugSessionID) error

ReleaseDebugSession reclaims a known debugger, joining any release in progress.

func (*ResourceStore) ReleaseExecution 

func (r *ResourceStore) ReleaseExecution(ctx context.Context, id ExecutionID) error

ReleaseExecution cancels and reclaims a known execution, joining any release in progress.

func (*ResourceStore) ReleasePlan 

func (r *ResourceStore) ReleasePlan(ctx context.Context, id PlanID) error

ReleasePlan tears down a known plan and its descendants, joining any release in progress.

func (*ResourceStore) ReleaseSession 

func (r *ResourceStore) ReleaseSession(ctx context.Context, id SessionID) error

ReleaseSession tears down a known session and its execution, joining any release in progress.

func (*ResourceStore) Session 

func (r *ResourceStore) Session(ctx context.Context, id SessionID) (*Session, error)

Session resolves a live session in this connection and rejects handles being released.

type Session 

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

Session owns one durable hosted session. Its execution slot remains occupied through execution release, including after the run reaches a terminal state.

func (*Session) Execute 

func (s *Session) Execute(ctx context.Context) (*Execution, error)

Execute starts a run only when the session's previous execution has been released.

func (*Session) ID 

func (s *Session) ID() SessionID

ID identifies this durable session within its logical connection.

func (*Session) Release 

func (s *Session) Release(ctx context.Context) error

Release cancels the session, releases its execution, and closes the hosted session. Caller cancellation stops waiting without abandoning teardown.

type SessionID 

type SessionID string

SessionID is the opaque registry key for a durable session.

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.