executor

Documentation

Overview

Package executor defines the trusted execution boundary used by Ramen apply and reconciliation operations, together with credential-free mock and recorded implementations.

The executor package is part of Ramen's supported v0.1 core API.

Index

• Constants
• func AsyncConfirmationReadObservationEvidence(req Request, result Result, execErr error, ...) asyncevidence.ConfirmationReadObservation
• func AsyncExecutionRequestEvidence(req Request, evidenceID, attemptID string, sequence int64, ...) asyncevidence.ExecutionRequest
• func AsyncExecutionResponseEvidence(req Request, result Result, execErr error, ...) asyncevidence.ExecutionResponse
• func AsyncStatusObservationEvidence(req Request, event Event, evidenceID, attemptID, requestEvidenceID string, ...) asyncevidence.StatusObservation
• func EnsureSupported(exec Executor, req Request) error
• func RequestKey(req Request) string
• type Action
• type ActionMapping
• type CapabilityDescriptor
• type CapabilityRequirement
  • func RequirementsForAction(action Action) CapabilityRequirement
  • func RequirementsForRuntimeHints(req CapabilityRequirement, hints RuntimeHints) CapabilityRequirement
• type Capable
• type Event
  • func Emit(req Request, phase, message string, metadata map[string]any) Event
• type EventSink
• type Executor
• type FeedbackRecord
  • func FeedbackFromResult(req Request, result Result, err error) FeedbackRecord
• type Idempotency
  • func IdempotencyForAction(action Action) Idempotency
• type MockExecutor
  • func (m *MockExecutor) Capabilities() CapabilityDescriptor
  • func (m *MockExecutor) Execute(ctx context.Context, req Request) (Result, error)
  • func (m *MockExecutor) RequestCount() int
• type RecordedCall
• type RecordedExecutor
  • func LoadRecording(path string) (*RecordedExecutor, error)
  • func NewRecordedExecutor(calls []RecordedCall) *RecordedExecutor
  • func (r *RecordedExecutor) Capabilities() CapabilityDescriptor
  • func (r *RecordedExecutor) Execute(ctx context.Context, req Request) (Result, error)
  • func (r *RecordedExecutor) Save(path string) error
• type Recording
• type Request
• type Result
  • func RedactResult(result Result) Result
• type RuntimeHints

Examples

• Executor

Constants

const (
	FeatureOutputIdentity  = "output.identity"
	FeatureOutputComputed  = "output.computed"
	FeatureMissingEvidence = "output.missing"
	FeatureProgressEvents  = "progress.events"
	FeatureIdempotency     = "idempotency"
	FeatureRetry           = "retry"
	FeatureWaiter          = "waiter"
	FeaturePagination      = "pagination"
)

const FeedbackVersion = "ramen.feedback.v1"

Functions

func AsyncConfirmationReadObservationEvidence

func AsyncConfirmationReadObservationEvidence(req Request, result Result, execErr error, evidenceID, attemptID, requestEvidenceID string, sequence int64, observedAt time.Time) asyncevidence.ConfirmationReadObservation

func AsyncExecutionRequestEvidence

func AsyncExecutionRequestEvidence(req Request, evidenceID, attemptID string, sequence int64, recordedAt time.Time) asyncevidence.ExecutionRequest

func AsyncExecutionResponseEvidence

func AsyncExecutionResponseEvidence(req Request, result Result, execErr error, evidenceID, attemptID, requestEvidenceID string, sequence int64, recordedAt time.Time) asyncevidence.ExecutionResponse

func AsyncStatusObservationEvidence

func AsyncStatusObservationEvidence(req Request, event Event, evidenceID, attemptID, requestEvidenceID string, sequence int64) asyncevidence.StatusObservation

func EnsureSupported

func EnsureSupported(exec Executor, req Request) error

func RequestKey

func RequestKey(req Request) string

Types

type Action

type Action struct {
	Address     string            `json:"address"`
	Type        string            `json:"type"`
	Provider    string            `json:"provider,omitempty"`
	Action      string            `json:"action"`
	DesiredHash string            `json:"desired_hash,omitempty"`
	Mapping     ActionMapping     `json:"mapping"`
	Metadata    map[string]string `json:"metadata,omitempty"`
}

Action describes one approved plan action handed to a trusted executor.

type ActionMapping

type ActionMapping struct {
	Method      string `json:"method,omitempty"`
	SourceKind  string `json:"source_kind,omitempty"`
	SourceID    string `json:"source_id,omitempty"`
	SourcePath  string `json:"source_path,omitempty"`
	OperationID string `json:"operation_id,omitempty"`
}

type CapabilityDescriptor

type CapabilityDescriptor struct {
	Protocols   []string `json:"protocols,omitempty"`
	AuthSchemes []string `json:"auth_schemes,omitempty"`
	Features    []string `json:"features,omitempty"`
}

type CapabilityRequirement

type CapabilityRequirement struct {
	Protocol string   `json:"protocol,omitempty"`
	Features []string `json:"features,omitempty"`
}

func RequirementsForAction

func RequirementsForAction(action Action) CapabilityRequirement

func RequirementsForRuntimeHints

func RequirementsForRuntimeHints(req CapabilityRequirement, hints RuntimeHints) CapabilityRequirement

type Capable

type Capable interface {
	Capabilities() CapabilityDescriptor
}

type Event

type Event struct {
	Time      time.Time      `json:"time,omitempty"`
	RunID     int64          `json:"run_id,omitempty"`
	Address   string         `json:"address,omitempty"`
	Action    string         `json:"action,omitempty"`
	Operation string         `json:"operation,omitempty"`
	Phase     string         `json:"phase"`
	Message   string         `json:"message,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

func Emit

func Emit(req Request, phase, message string, metadata map[string]any) Event

type EventSink

type EventSink func(Event)

type Executor

type Executor interface {
	Capable
	Execute(context.Context, Request) (Result, error)
}

Executor executes one approved action document and declares the capabilities that Ramen must verify before handing the action across the trust boundary.

Example

package main

import (
	"context"
	"fmt"

	"github.com/OpenUdon/ramen/executor"
)

// platformExecutor is a credential-free example of Ramen's in-process trusted
// executor contract. Production adapters keep credentials in executor-owned
// configuration rather than in executor.Request.
type platformExecutor struct{}

func (platformExecutor) Capabilities() executor.CapabilityDescriptor {
	return executor.CapabilityDescriptor{
		Protocols:   []string{"openapi"},
		AuthSchemes: []string{"executor-configured"},
		Features: []string{
			executor.FeatureIdempotency,
			executor.FeatureProgressEvents,
			executor.FeatureOutputIdentity,
			executor.FeatureOutputComputed,
		},
	}
}

func (platformExecutor) Execute(_ context.Context, req executor.Request) (executor.Result, error) {
	return executor.Result{
		Address:   req.Action.Address,
		Operation: req.Action.Mapping.OperationID,
		Success:   true,
		Identity:  map[string]any{"name": "example"},
	}, nil
}

func main() {
	var adapter executor.Executor = platformExecutor{}
	action := executor.Action{
		Address: "widget.example",
		Action:  "create",
		Mapping: executor.ActionMapping{
			SourceKind:  "openapi",
			OperationID: "createWidget",
		},
	}
	req := executor.Request{
		Action:       action,
		Capabilities: executor.RequirementsForAction(action),
		Idempotency:  executor.IdempotencyForAction(action),
	}
	result, err := adapter.Execute(context.Background(), req)
	fmt.Println(result.Success, result.Operation, err)
}

Output:
true createWidget <nil>

type FeedbackRecord

type FeedbackRecord struct {
	Version    string         `json:"version"`
	RunID      int64          `json:"run_id,omitempty"`
	Address    string         `json:"address"`
	Action     string         `json:"action"`
	Operation  string         `json:"operation,omitempty"`
	Success    bool           `json:"success"`
	Missing    bool           `json:"missing,omitempty"`
	ErrorClass string         `json:"error_class,omitempty"`
	Identity   map[string]any `json:"identity,omitempty"`
	Computed   map[string]any `json:"computed,omitempty"`
	Messages   []string       `json:"messages,omitempty"`
	Events     []Event        `json:"events,omitempty"`
	StartedAt  time.Time      `json:"started_at,omitempty"`
	FinishedAt time.Time      `json:"finished_at,omitempty"`
}

func FeedbackFromResult

func FeedbackFromResult(req Request, result Result, err error) FeedbackRecord

type Idempotency

type Idempotency struct {
	Key       string `json:"key,omitempty"`
	Scope     string `json:"scope,omitempty"`
	Supported bool   `json:"supported,omitempty"`
}

func IdempotencyForAction

func IdempotencyForAction(action Action) Idempotency

type MockExecutor

type MockExecutor struct {
	Requests  []Request
	Results   map[string]Result
	ExecuteFn func(context.Context, Request) (Result, error)
	// contains filtered or unexported fields
}

MockExecutor is a deterministic executor for public tests and recorded examples. It never performs network I/O.

func (*MockExecutor) Capabilities

func (m *MockExecutor) Capabilities() CapabilityDescriptor

func (*MockExecutor) Execute

func (m *MockExecutor) Execute(ctx context.Context, req Request) (Result, error)

func (*MockExecutor) RequestCount

func (m *MockExecutor) RequestCount() int

type RecordedCall

type RecordedCall struct {
	Key     string  `json:"key"`
	Request Request `json:"request"`
	Result  Result  `json:"result"`
	Error   string  `json:"error,omitempty"`
}

type RecordedExecutor

type RecordedExecutor struct {
	Records  map[string]RecordedCall
	Recorder Executor
	Calls    []RecordedCall
	// contains filtered or unexported fields
}

func LoadRecording

func LoadRecording(path string) (*RecordedExecutor, error)

func NewRecordedExecutor

func NewRecordedExecutor(calls []RecordedCall) *RecordedExecutor

func (*RecordedExecutor) Capabilities

func (r *RecordedExecutor) Capabilities() CapabilityDescriptor

func (*RecordedExecutor) Execute

func (r *RecordedExecutor) Execute(ctx context.Context, req Request) (Result, error)

func (*RecordedExecutor) Save

func (r *RecordedExecutor) Save(path string) error

type Recording

type Recording struct {
	Version string         `json:"version"`
	Calls   []RecordedCall `json:"calls"`
}

type Request

type Request struct {
	RunID        int64                 `json:"run_id,omitempty"`
	Action       Action                `json:"action"`
	Document     *uws1.Document        `json:"-"`
	WorkingDir   string                `json:"working_dir,omitempty"`
	OutDir       string                `json:"out_dir,omitempty"`
	Capabilities CapabilityRequirement `json:"capabilities,omitempty"`
	Idempotency  Idempotency           `json:"idempotency,omitempty"`
	Runtime      RuntimeHints          `json:"runtime,omitempty"`
	Events       EventSink             `json:"-"`
}

Request is the explicit trusted-executor boundary. Credential material must stay in executor-owned configuration and must not be embedded here.

type Result

type Result struct {
	Address    string         `json:"address,omitempty"`
	Operation  string         `json:"operation,omitempty"`
	Success    bool           `json:"success"`
	Missing    bool           `json:"missing,omitempty"`
	Identity   map[string]any `json:"identity,omitempty"`
	Computed   map[string]any `json:"computed,omitempty"`
	Messages   []string       `json:"messages,omitempty"`
	Events     []Event        `json:"events,omitempty"`
	StartedAt  time.Time      `json:"started_at,omitempty"`
	FinishedAt time.Time      `json:"finished_at,omitempty"`
}

Result captures response-derived facts that Ramen may persist after redaction. Raw request and response bodies remain executor-owned.

func RedactResult

func RedactResult(result Result) Result

type RuntimeHints

type RuntimeHints struct {
	Retry      map[string]any `json:"retry,omitempty"`
	Waiter     map[string]any `json:"waiter,omitempty"`
	Pagination map[string]any `json:"pagination,omitempty"`
}