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

executioncontroller

package
v0.0.42 Latest Latest
Warning

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

 Go to latest Published: Sep 29, 2026 License: Apache-2.0 Imports: 58 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 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 {
	ValidateProfile(context.Context, string) (Profile, error)
	Ensure(context.Context, string, string, string, string, string) (Allocation, error)
	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
}

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 GrantSigner 

type GrantSigner struct {
	KeyID            string
	PrivateKey       ed25519.PrivateKey
	Issuer, Audience string
	Lifetime         time.Duration
}

GrantSigner configures short-lived environment grant issuance.

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 and issues a run-bound grant.

func (*Handler) AttachEnvironment 

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

AttachEnvironment exactly reattaches and refreshes a short-lived grant.

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) EnsureEnvironment 

func (h *Handler) EnsureEnvironment(ctx context.Context, q *executionv1.EnsureEnvironmentRequest) (*executionv1.EnsureEnvironmentResponse, error)

EnsureEnvironment idempotently resolves or allocates an environment.

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) ListReferenceIntents 

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

func (*Handler) MigrateEnvironment 

func (h *Handler) MigrateEnvironment(ctx context.Context, q *executionv1.MigrateEnvironmentRequest) (*emptypb.Empty, 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) ValidateProfile 

func (h *Handler) ValidateProfile(ctx context.Context, q *executionv1.ValidateProfileRequest) (*executionv1.ValidateProfileResponse, error)

ValidateProfile validates one operator-defined execution profile.

type HandlerConfig 

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

HandlerConfig configures authentication and capability grants.

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"`
	MaxEnvironments         int                 `yaml:"maxEnvironments"`
}

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 LoadProfiles 

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

LoadProfiles reads and strictly validates an operator profile file.

func (*Profiles) WithExecutorServiceAccount 

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

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

type ProfilesFile 

type ProfilesFile struct {
	Profiles map[string]ProfileSpec `yaml:"profiles"`
}

ProfilesFile is the strict operator profile-file schema.

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) 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) Ensure 

func (s *Store) Ensure(ctx context.Context, client, owner, binding, profile, fp string) (Allocation, error)

Ensure idempotently allocates an environment for an immutable request fingerprint.

func (*Store) EnsurePending 

func (s *Store) EnsurePending(ctx context.Context, client, owner, binding, profile, fp, operationID string) (Allocation, error)

func (*Store) EnsurePendingOwned 

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

EnsurePendingOwned persists the attested principal needed for owner-safe intent reconciliation.

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) MigrateEnvironment 

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

MigrateEnvironment explicitly upgrades a recognized, verified prototype schema.

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) ValidateProfile 

func (s *Store) ValidateProfile(_ context.Context, name string) (Profile, error)

ValidateProfile returns one validated immutable profile.

func (*Store) ValidateRunClaim 

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

ValidateRunClaim rechecks durable generation and ownership before any grant-authorized operation.

func (*Store) WithKubeClient 

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

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

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.