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

executioncontroller

package
v0.0.49 Latest Latest
Warning

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

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

Documentation

Overview

Package executioncontroller implements the authenticated provider gRPC boundary.

Index

Constants

This section is empty.

Variables

View Source 
var ExecutionEnvironmentGVR = schema.GroupVersionResource{Group: "execution.mecatl.dev", Version: "v1alpha1", Resource: "executionenvironments"}

ExecutionEnvironmentGVR identifies the private execution-environment CRD.

Functions

func CanonicalTemplateRevision added in v0.0.48 

func CanonicalTemplateRevision(spec ProfileSpec) (string, error)

CanonicalTemplateRevision returns the v1 identity of the execution recipe. Admission policy and display metadata are deliberately outside ProfileSpec. Call LoadTemplates to validate the complete definition before publishing it.

func TLSConfig 

func TLSConfig(server tls.Certificate, clientCAs *x509.CertPool) *tls.Config

TLSConfig returns the provider's TLS 1.3 mutual-authentication policy.

Types

type Allocation 

type Allocation struct {
	Environment                  executionenv.EnvironmentRef
	Epoch, GrantGeneration       uint64
	OwnerHash, BindingID, Client string
	Ready                        bool
}

Allocation is an exact environment allocation and authorization binding.

type Backend 

type Backend interface {
	Attach(context.Context, executionenv.EnvironmentRef, string, string, string) (Allocation, error)
	ReleaseReference(context.Context, executionenv.EnvironmentRef, string, string, string) error
	File(context.Context, string, string, executionenv.FileRequest) (executionenv.FileResponse, error)
	StartCommand(context.Context, string, string, executionenv.CommandStartRequest) (executionenv.CommandStartResponse, error)
	CommandStatus(context.Context, string, string, executionenv.CommandQueryRequest) (executionenv.CommandStatusResponse, error)
	CancelCommand(context.Context, string, string, executionenv.CommandQueryRequest) (executionenv.CommandStatusResponse, error)
}

Backend implements provider-side authorization state and executor dispatch.

type ClientPolicy 

type ClientPolicy struct {
	MayAttestOwner, Administrator bool
	AdministratorFor              []string
	ExecutionTemplates            []string
}

ClientPolicy defines capabilities assigned to an authenticated provider client.

type ExecutorTransport 

type ExecutorTransport interface {
	Execute(context.Context, string, executionenv.ExecutorRequest) (executionenv.ExecutorResponse, error)
}

ExecutorTransport dispatches one request to a fixed workload helper.

type Handler 

type Handler struct {
	executionv1.UnimplementedExecutionProviderServiceServer
	// contains filtered or unexported fields
}

Handler is the authenticated private execution-provider gRPC service.

func NewHandler 

func NewHandler(cfg HandlerConfig, b Backend) *Handler

NewHandler constructs the authenticated private gRPC service.

func (*Handler) AbortReference 

func (h *Handler) AbortReference(ctx context.Context, q *executionv1.ReferenceMutationRequest) (*emptypb.Empty, error)

func (*Handler) AcquireRun 

func (h *Handler) AcquireRun(ctx context.Context, q *executionv1.AcquireRunRequest) (*executionv1.RunClaimResponse, error)

AcquireRun takes environment-wide execution ownership.

func (*Handler) AttachEnvironment 

func (h *Handler) AttachEnvironment(ctx context.Context, q *executionv1.AttachEnvironmentRequest) (*executionv1.AttachEnvironmentResponse, error)

AttachEnvironment exactly reattaches to a durable reference.

func (*Handler) CancelCommand 

func (h *Handler) CancelCommand(ctx context.Context, q *executionv1.CommandQueryRequest) (*executionv1.CommandStatusResponse, error)

CancelCommand authorizes then reports the detached API as unsupported.

func (*Handler) CancelReferenceDelete 

func (h *Handler) CancelReferenceDelete(ctx context.Context, q *executionv1.ReferenceMutationRequest) (*emptypb.Empty, error)

func (*Handler) CommandStatus 

func (h *Handler) CommandStatus(ctx context.Context, q *executionv1.CommandQueryRequest) (*executionv1.CommandStatusResponse, error)

CommandStatus authorizes then reports the detached API as unsupported.

func (*Handler) CommitReference 

func (h *Handler) CommitReference(ctx context.Context, q *executionv1.ReferenceMutationRequest) (*emptypb.Empty, error)

func (*Handler) ConfirmReferenceDelete 

func (h *Handler) ConfirmReferenceDelete(ctx context.Context, q *executionv1.ReferenceMutationRequest) (*emptypb.Empty, error)

func (*Handler) DeleteRetiredEnvironment 

func (h *Handler) DeleteRetiredEnvironment(ctx context.Context, q *executionv1.DeleteRetiredEnvironmentRequest) (*emptypb.Empty, error)

func (*Handler) EnsureTemplate added in v0.0.48 

func (h *Handler) EnsureTemplate(ctx context.Context, q *executionv1.EnsureTemplateRequest) (*executionv1.EnsureEnvironmentResponse, error)

EnsureTemplate allocates a caller-authorized exact template revision.

func (*Handler) Files 

func (h *Handler) Files(ctx context.Context, q *executionv1.FileRequest) (*executionv1.FileResponse, error)

Files executes one bounded and authorized filesystem operation.

func (*Handler) ListExecutionTemplates added in v0.0.48 

func (h *Handler) ListExecutionTemplates(ctx context.Context, _ *executionv1.ListExecutionTemplatesRequest) (*executionv1.ListExecutionTemplatesResponse, error)

ListExecutionTemplates returns the caller's allowed selectable template catalog.

func (*Handler) ListReferenceIntents 

func (h *Handler) ListReferenceIntents(ctx context.Context, q *executionv1.ListReferenceIntentsRequest) (*executionv1.ListReferenceIntentsResponse, error)

func (*Handler) PrepareReferenceDelete 

func (h *Handler) PrepareReferenceDelete(ctx context.Context, q *executionv1.ReferenceMutationRequest) (*emptypb.Empty, error)

func (*Handler) RecoverEnvironment 

func (h *Handler) RecoverEnvironment(ctx context.Context, q *executionv1.RecoverEnvironmentRequest) (*emptypb.Empty, error)

func (*Handler) ReleaseReference 

func (h *Handler) ReleaseReference(ctx context.Context, q *executionv1.ReleaseReferenceRequest) (*emptypb.Empty, error)

ReleaseReference releases one authorized durable binding reference.

func (*Handler) ReleaseRun 

func (h *Handler) ReleaseRun(ctx context.Context, q *executionv1.ReleaseRunRequest) (*emptypb.Empty, error)

func (*Handler) RenewRun 

func (h *Handler) RenewRun(ctx context.Context, q *executionv1.RenewRunRequest) (*executionv1.RunClaimResponse, error)

func (*Handler) ReplaceExecutor 

func (h *Handler) ReplaceExecutor(ctx context.Context, q *executionv1.ReplaceExecutorRequest) (*emptypb.Empty, error)

func (*Handler) ReserveSuccessor 

func (h *Handler) ReserveSuccessor(ctx context.Context, q *executionv1.ReserveSuccessorRequest) (*executionv1.ReferenceReservationResponse, error)

func (*Handler) RetireEnvironment 

func (h *Handler) RetireEnvironment(ctx context.Context, q *executionv1.RetireEnvironmentRequest) (*emptypb.Empty, error)

RetireEnvironment starts exact, proof-producing executor retirement while retaining the PVC.

func (*Handler) RevokeEnvironment 

func (h *Handler) RevokeEnvironment(ctx context.Context, q *executionv1.RevokeEnvironmentRequest) (*executionv1.RevokeEnvironmentResponse, error)

func (*Handler) StartCommand 

func (h *Handler) StartCommand(ctx context.Context, q *executionv1.CommandStartRequest) (*executionv1.CommandStartResponse, error)

StartCommand executes one authorized foreground command.

func (*Handler) ValidateTemplate added in v0.0.48 

func (h *Handler) ValidateTemplate(ctx context.Context, q *executionv1.ValidateTemplateRequest) (*executionv1.ValidateTemplateResponse, error)

ValidateTemplate resolves a caller-authorized exact template revision.

type HandlerConfig 

type HandlerConfig struct {
	Clients     map[string]ClientPolicy
	Ready       func() bool
	Security    *SecurityManager
	Diagnostics port.Diagnostics
}

HandlerConfig configures authenticated client policy.

type PodExecutor 

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

PodExecutor invokes the fixed helper in an already-selected executor Pod.

func NewPodExecutor 

func NewPodExecutor(config *rest.Config, kube kubernetes.Interface, namespace string) *PodExecutor

NewPodExecutor constructs a namespace-scoped Pod executor transport.

func (*PodExecutor) Execute 

func (p *PodExecutor) Execute(ctx context.Context, pod string, q executionenv.ExecutorRequest) (executionenv.ExecutorResponse, error)

Execute runs one bounded helper request in pod.

type Profile 

type Profile struct {
	Name, Digest                  string
	MaxFileBytes, MaxCommandBytes int64
	MaxCommandDuration            time.Duration
	Capabilities                  []string
}

Profile is the externally visible immutable execution profile.

type ProfileSpec 

type ProfileSpec struct {
	Image                   string              `yaml:"image"`
	StorageClass            string              `yaml:"storageClass"`
	StorageSize             string              `yaml:"storageSize"`
	CPURequest              string              `yaml:"cpuRequest"`
	MemoryRequest           string              `yaml:"memoryRequest"`
	CPULimit                string              `yaml:"cpuLimit"`
	MemoryLimit             string              `yaml:"memoryLimit"`
	EphemeralStorageRequest string              `yaml:"ephemeralStorageRequest"`
	EphemeralStorageLimit   string              `yaml:"ephemeralStorageLimit"`
	TmpSizeLimit            string              `yaml:"tmpSizeLimit"`
	RuntimeClassName        string              `yaml:"runtimeClassName"`
	ImagePullSecrets        []string            `yaml:"imagePullSecrets,omitempty"`
	NodeSelector            map[string]string   `yaml:"nodeSelector,omitempty"`
	Tolerations             []corev1.Toleration `yaml:"tolerations,omitempty"`
	MaxFileBytes            int64               `yaml:"maxFileBytes"`
	MaxCommandBytes         int64               `yaml:"maxCommandBytes"`
	MaxCommandDuration      time.Duration       `yaml:"maxCommandDuration"`
}

ProfileSpec defines immutable image, storage, resource, and operation bounds.

type Profiles 

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

Profiles is a validated immutable profile registry.

func LoadTemplates added in v0.0.48 

func LoadTemplates(path string) (*Profiles, error)

LoadTemplates rejects unknown fields and any revision not matching its v1 canonical execution digest. Display and policy edits do not change revisions.

func (*Profiles) DefaultRevision added in v0.0.48 

func (p *Profiles) DefaultRevision(id string) string

DefaultRevision returns the exact operator-pinned revision for an ID.

func (*Profiles) WithExecutorServiceAccount 

func (p *Profiles) WithExecutorServiceAccount(name string) *Profiles

WithExecutorServiceAccount sets the chart-owned identity for Pod construction and validation.

type RPCLimiter 

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

RPCLimiter bounds active unary RPCs globally and per authorized client.

func NewRPCLimiter 

func NewRPCLimiter(security *SecurityManager, globalMax, clientMax int) (*RPCLimiter, error)

NewRPCLimiter constructs a limiter whose client map is bounded by the security allowlist.

func (*RPCLimiter) UnaryInterceptor 

func (l *RPCLimiter) UnaryInterceptor(ctx context.Context, req any, _ *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (any, error)

UnaryInterceptor authenticates against current policy before reserving capacity.

type Reconciler 

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

Reconciler maintains executor Pods and retained workspace PVCs.

func NewReconciler 

func NewReconciler(d dynamic.Interface, k kubernetes.Interface, namespace string, p *Profiles) *Reconciler

NewReconciler constructs a reconciler for one namespace.

func (*Reconciler) Initialize 

func (r *Reconciler) Initialize(ctx context.Context) error

Initialize synchronizes informer caches before the provider may expose mutating APIs. Startup never mutates operation ownership: another replica may still be its live holder.

func (*Reconciler) ReadinessReason 

func (r *Reconciler) ReadinessReason() string

ReadinessReason returns a bounded operator-facing reason class.

func (*Reconciler) Ready 

func (r *Reconciler) Ready() bool

Ready reports whether startup fencing, profile preflight, and informer synchronization completed.

func (*Reconciler) Reconcile 

func (r *Reconciler) Reconcile(ctx context.Context, name string) error

Reconcile converges one ExecutionEnvironment and its runtime resources.

func (*Reconciler) Run 

func (r *Reconciler) Run(ctx context.Context) error

Run initializes the reconciler and blocks until shutdown.

type SecurityManager 

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

SecurityManager reloads one immutable, versioned security snapshot from projected files and binds its generation to a durable ConfigMap high-water mark.

func NewSecurityManager 

func NewSecurityManager(manifestPath, keyDirectory, namespace, configMap string, kube kubernetes.Interface) *SecurityManager

NewSecurityManager constructs a fail-closed security material reloader.

func (*SecurityManager) CheckReady 

func (m *SecurityManager) CheckReady(ctx context.Context) bool

CheckReady verifies that the loaded snapshot still matches durable authority.

func (*SecurityManager) Ready 

func (m *SecurityManager) Ready() bool

Ready reports whether the current snapshot is authoritative and unexpired.

func (*SecurityManager) Reload 

func (m *SecurityManager) Reload(ctx context.Context) error

Reload atomically validates and publishes a complete security snapshot.

func (*SecurityManager) Run 

func (m *SecurityManager) Run(ctx context.Context, interval time.Duration)

Run periodically reloads security material until ctx is cancelled.

func (*SecurityManager) TLSConfig 

func (m *SecurityManager) TLSConfig() *tls.Config

TLSConfig returns a dynamic TLS configuration backed by the current snapshot.

type Store 

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

Store persists authorization and fencing state in ExecutionEnvironment status.

func NewStore 

func NewStore(client dynamic.Interface, namespace string, profiles *Profiles, executor ExecutorTransport) *Store

NewStore constructs a namespace-scoped execution state store.

func (*Store) AbortReference 

func (s *Store) AbortReference(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding, operation string) error

func (*Store) AcquireRun 

func (s *Store) AcquireRun(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding, runID, operationID string, ttl time.Duration) (executionenv.RunClaim, error)

func (*Store) Attach 

func (s *Store) Attach(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding string) (Allocation, error)

Attach adds a binding reference only to the exact healthy environment.

func (*Store) CancelCommand 

func (*Store) CancelCommand(context.Context, string, string, executionenv.CommandQueryRequest) (executionenv.CommandStatusResponse, error)

CancelCommand refuses cancellation without an attached foreground control stream.

func (*Store) CancelReferenceDelete 

func (s *Store) CancelReferenceDelete(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding, operation string) error

func (*Store) CatalogTemplates added in v0.0.48 

func (s *Store) CatalogTemplates() []*executionv1.TemplateCatalogItem

CatalogTemplates returns all selectable template revisions.

func (*Store) CommandStatus 

func (*Store) CommandStatus(context.Context, string, string, executionenv.CommandQueryRequest) (executionenv.CommandStatusResponse, error)

CommandStatus reports that foreground-only commands have no detached status API.

func (*Store) CommitReference 

func (s *Store) CommitReference(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding, operation string) error

func (*Store) ConfirmReferenceDelete 

func (s *Store) ConfirmReferenceDelete(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding, operation string) error

func (*Store) DeleteRetiredEnvironment 

func (s *Store) DeleteRetiredEnvironment(ctx context.Context, q adminLifecycleRequest) error

DeleteRetiredEnvironment starts exact deletion of an explicitly retained workspace.

func (*Store) EnsurePendingOwnedRevision added in v0.0.48 

func (s *Store) EnsurePendingOwnedRevision(ctx context.Context, client, expectedOwnerHash string, owner executionenv.Owner, binding, id, revision, fp, operationID string) (Allocation, error)

EnsurePendingOwnedRevision binds an exact eligible definition. Repeated requests for the final binding ID must supply the same revision and fingerprint.

func (*Store) File 

func (s *Store) File(ctx context.Context, client, owner string, q executionenv.FileRequest) (executionenv.FileResponse, error)

File performs one claimed and fenced filesystem operation.

func (*Store) FindReferenceIntent 

func (s *Store) FindReferenceIntent(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding string) (executionenv.ReferenceIntent, error)

func (*Store) ListReferenceIntents 

func (s *Store) ListReferenceIntents(ctx context.Context, client, owner string, limit int) ([]executionenv.ReferenceIntent, error)

func (*Store) ListReferenceIntentsForClient 

func (s *Store) ListReferenceIntentsForClient(ctx context.Context, client string, limit int) ([]executionenv.ReferenceIntent, error)

func (*Store) PrepareReferenceDelete 

func (s *Store) PrepareReferenceDelete(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding, operation string) error

func (*Store) RecoverEnvironment 

func (s *Store) RecoverEnvironment(ctx context.Context, q adminLifecycleRequest) error

RecoverEnvironment clears uncertainty only after built-in exact terminal verification.

func (*Store) ReleaseReference 

func (s *Store) ReleaseReference(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, binding string) error

ReleaseReference removes one binding reference without deleting the environment.

func (*Store) ReleaseRun 

func (s *Store) ReleaseRun(ctx context.Context, ref executionenv.EnvironmentRef, client, owner string, req executionenv.RunClaimRequest) error

func (*Store) RenewRun 

func (s *Store) RenewRun(ctx context.Context, ref executionenv.EnvironmentRef, client, owner string, req executionenv.RunClaimRequest) (executionenv.RunClaim, error)

func (*Store) ReplaceExecutor 

func (s *Store) ReplaceExecutor(ctx context.Context, q adminLifecycleRequest) error

ReplaceExecutor starts an exact, crash-recoverable executor replacement.

func (*Store) ReserveSuccessor 

func (s *Store) ReserveSuccessor(ctx context.Context, ref executionenv.EnvironmentRef, client, owner, source, destination, operation string) error

func (*Store) RetireExact 

func (s *Store) RetireExact(ctx context.Context, q adminLifecycleRequest) error

RetireExact starts exact executor retirement while retaining its workspace.

func (*Store) RevokeEnvironment 

func (s *Store) RevokeEnvironment(ctx context.Context, q adminLifecycleRequest, expected uint64) (uint64, error)

RevokeEnvironment atomically invalidates every issued grant without claiming that an already-dispatched executor operation has stopped.

func (*Store) StartCommand 

func (s *Store) StartCommand(ctx context.Context, client, owner string, q executionenv.CommandStartRequest) (executionenv.CommandStartResponse, error)

StartCommand performs one claimed foreground command through terminal receipt.

func (*Store) ValidateRunClaim 

func (s *Store) ValidateRunClaim(ctx context.Context, client, owner string, rc executionenv.RequestContext) error

ValidateRunClaim checks the durable run, binding, client and current policy before dispatch.

func (*Store) ValidateTemplate added in v0.0.48 

func (s *Store) ValidateTemplate(_ context.Context, id, revision string) (Profile, error)

ValidateTemplate resolves one exact selectable template revision.

func (*Store) WithKubeClient 

func (s *Store) WithKubeClient(kube kubernetes.Interface) *Store

WithKubeClient enables provider-owned executor and retained-volume lifecycle operations.

func (*Store) WithSecurityManager added in v0.0.48 

func (s *Store) WithSecurityManager(security *SecurityManager) *Store

WithSecurityManager fences active work when its client loses current policy authority.

type TemplateDefinition added in v0.0.48 

type TemplateDefinition struct {
	Default         string                      `yaml:"default"`
	MaxEnvironments int                         `yaml:"maxEnvironments"`
	Revisions       map[string]TemplateRevision `yaml:"revisions"`
}

TemplateDefinition is the operator-owned template and revision declaration.

type TemplateDisplay added in v0.0.48 

type TemplateDisplay struct {
	Name        string                       `yaml:"name,omitempty" json:"name,omitempty"`
	Description string                       `yaml:"description,omitempty" json:"description,omitempty"`
	Extensions  map[string]map[string]string `yaml:"extensions,omitempty" json:"extensions,omitempty"`
}

TemplateDisplay is inert operator-authored data, never injected into prompts. Extensions are bounded, versioned, namespaced string maps for client display.

type TemplatePolicy added in v0.0.48 

type TemplatePolicy struct {
	Deprecated bool
	Revoked    bool
}

TemplatePolicy describes whether a revision remains selectable or retained only.

type TemplateRevision added in v0.0.48 

type TemplateRevision struct {
	Execution  ProfileSpec     `yaml:"execution"`
	Deprecated bool            `yaml:"deprecated,omitempty"`
	Revoked    bool            `yaml:"revoked,omitempty"`
	Display    TemplateDisplay `yaml:"display,omitempty"`
}

TemplateRevision is one immutable execution definition and its lifecycle policy.

type TemplatesFile added in v0.0.48 

type TemplatesFile struct {
	Templates map[string]TemplateDefinition `yaml:"templates"`
}

TemplatesFile is the single operator-owned execution definition source. A published revision must remain in this file while any allocation retains it.

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.