extensiontest

package
v0.0.7 Latest Latest
Warning

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

 Go to latest Published: Jun 4, 2026 License: MIT Imports: 29 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	EnvHandshakePath = "AGH_BRIDGE_ADAPTER_HANDSHAKE_PATH"
	EnvOwnershipPath = "AGH_BRIDGE_ADAPTER_OWNERSHIP_PATH"
	EnvStatePath     = "AGH_BRIDGE_ADAPTER_STATE_PATH"
	EnvDeliveryPath  = "AGH_BRIDGE_ADAPTER_DELIVERY_PATH"
	EnvIngestPath    = "AGH_BRIDGE_ADAPTER_INGEST_PATH"
	EnvUpdatesPath   = "AGH_BRIDGE_ADAPTER_UPDATES_PATH"
	EnvStartsPath    = "AGH_BRIDGE_ADAPTER_STARTS_PATH"
	EnvShutdownPath  = "AGH_BRIDGE_ADAPTER_SHUTDOWN_PATH"
	EnvCrashOncePath = "AGH_BRIDGE_ADAPTER_CRASH_ONCE_PATH"
)

Variables

This section is empty.

Functions

func AppendInboundUpdateMarker 

func AppendInboundUpdateMarker(t testing.TB, markers MarkerPaths, update any)

AppendInboundUpdateMarker appends one fake platform update line for the reference adapter marker contract.

func ValidateClassifiedOutcome 

func ValidateClassifiedOutcome(actual ClassifiedOutcome, expect ClassifiedOutcomeExpectation) error

ValidateClassifiedOutcome asserts that a classified recovery outcome matches the shared expectation.

func ValidateConformance 

func ValidateConformance(report ConformanceReport, expect ConformanceExpectation) error

ValidateConformance checks the adapter evidence against the reusable bridge adapter contract enforced by the harness.

func ValidateConformanceMatrix 

func ValidateConformanceMatrix(entries []ProviderConformanceSummary, requiredTargets ...CoverageTarget) error

ValidateConformanceMatrix checks that the reusable provider matrix covers the required targets.

Types

type ClassifiedOutcome 

type ClassifiedOutcome struct {
	Provider       string
	Classification OutcomeClass
	Status         bridgepkg.BridgeStatus
	Reason         bridgepkg.BridgeDegradationReason
	Retryable      bool
}

ClassifiedOutcome captures the observed structured state transition for a recovery class.

type ClassifiedOutcomeExpectation 

type ClassifiedOutcomeExpectation struct {
	Classification OutcomeClass
	Status         bridgepkg.BridgeStatus
	Reason         bridgepkg.BridgeDegradationReason
	Retryable      bool
}

ClassifiedOutcomeExpectation describes the expected structured result for a recovery class.

type ConformanceError 

type ConformanceError struct {
	Issues []ConformanceIssue
}

ConformanceError aggregates reusable harness failures.

func (*ConformanceError) Error 

func (e *ConformanceError) Error() string

type ConformanceExpectation 

type ConformanceExpectation struct {
	Provider                  string
	Platform                  string
	ManagedInstances          []ManagedInstanceExpectation
	RequireOwnedInstanceList  bool
	RequireOwnedInstanceFetch bool
	RequireStateReport        bool
	RequireDelivery           bool
	RequireResume             bool
}

ConformanceExpectation configures the reusable adapter validator.

type ConformanceIssue 

type ConformanceIssue struct {
	Code    string
	Message string
}

ConformanceIssue reports one adapter contract failure.

type ConformanceMatrixError 

type ConformanceMatrixError struct {
	Issues []ConformanceMatrixIssue
}

ConformanceMatrixError aggregates matrix validation failures.

func (*ConformanceMatrixError) Error 

func (e *ConformanceMatrixError) Error() string

type ConformanceMatrixIssue 

type ConformanceMatrixIssue struct {
	Code    string
	Message string
}

ConformanceMatrixIssue reports one matrix-level validation failure.

type ConformanceReport 

type ConformanceReport struct {
	Handshake  *HandshakeRecord
	Ownership  *OwnershipRecord
	States     []StateRecord
	Deliveries []DeliveryRecord
	Ingests    []IngestRecord
}

ConformanceReport is the collected adapter evidence used by the validator.

func ReportFromMarkers 

func ReportFromMarkers(t testing.TB, markers MarkerPaths) ConformanceReport

ReportFromMarkers reads the collected adapter evidence from one marker set.

type CoverageTarget 

type CoverageTarget string

CoverageTarget identifies one task-level verification target proven by a provider scenario. 

const (
	CoverageTargetMultiInstance     CoverageTarget = "multi_instance"
	CoverageTargetRestartRecovery   CoverageTarget = "restart_recovery"
	CoverageTargetDMPolicy          CoverageTarget = "dm_policy"
	CoverageTargetAuthDegradation   CoverageTarget = "auth_degradation"
	CoverageTargetRateLimitRecovery CoverageTarget = "rate_limit_recovery"
)

type DeliveryRecord 

type DeliveryRecord struct {
	PID     int                       `json:"pid"`
	Request bridgepkg.DeliveryRequest `json:"request"`
	Ack     *bridgepkg.DeliveryAck    `json:"ack,omitempty"`
	Error   string                    `json:"error,omitempty"`
}

DeliveryRecord captures one `bridges/deliver` request plus the adapter ack when the subprocess remained alive long enough to return it.

func WaitForDeliveryMarkers 

func WaitForDeliveryMarkers(
	t testing.TB,
	markers MarkerPaths,
	timeout time.Duration,
	predicate func([]DeliveryRecord) bool,
) []DeliveryRecord

WaitForDeliveryMarkers waits until the delivery marker file satisfies the predicate.

type HandshakeRecord 

type HandshakeRecord struct {
	Request  subprocess.InitializeRequest  `json:"request"`
	Response subprocess.InitializeResponse `json:"response"`
}

HandshakeRecord captures the adapter initialize marker.

func WaitForHandshakeMarker 

func WaitForHandshakeMarker(t testing.TB, markers MarkerPaths, timeout time.Duration) HandshakeRecord

WaitForHandshakeMarker waits until the adapter writes its initialize marker.

type Harness 

type Harness struct {
	HomePaths aghconfig.HomePaths
	Markers   MarkerPaths
	Observer  *observepkg.Observer
	Bridges   *bridgepkg.Service
	Broker    *bridgepkg.Broker
	Handler   *extensionpkg.HostAPIHandler
	Manager   *extensionpkg.Manager
	Sessions  *session.Manager
	Instances []bridgepkg.BridgeInstance
}

Harness wires the manager, host API, session manager, observer, and marker contract used to validate bridge adapters end to end.

func NewHarness 

func NewHarness(t testing.TB, cfg HarnessConfig) *Harness

NewHarness starts the reusable adapter conformance harness.

func (*Harness) AppendInboundUpdate 

func (h *Harness) AppendInboundUpdate(t testing.TB, update any)

AppendInboundUpdate appends one fake platform update line for the adapter to ingest.

func (*Harness) ObserveHealth 

func (h *Harness) ObserveHealth(t testing.TB) observepkg.Health

ObserveHealth returns the current observer health surface.

func (*Harness) QueryBridgeHealth 

func (h *Harness) QueryBridgeHealth(t testing.TB) []observepkg.BridgeInstanceHealth

QueryBridgeHealth returns the current per-instance bridge health rows.

func (*Harness) Report 

func (h *Harness) Report(t testing.TB) ConformanceReport

Report reads the current collected adapter evidence into one reusable report.

func (*Harness) WaitForDeliveries 

func (h *Harness) WaitForDeliveries(
	t testing.TB,
	timeout time.Duration,
	predicate func([]DeliveryRecord) bool,
) []DeliveryRecord

WaitForDeliveries waits until the delivery marker file satisfies the predicate.

func (*Harness) WaitForHandshake 

func (h *Harness) WaitForHandshake(t testing.TB, timeout time.Duration) HandshakeRecord

WaitForHandshake waits until the adapter writes its initialize marker.

func (*Harness) WaitForIngests 

func (h *Harness) WaitForIngests(
	t testing.TB,
	timeout time.Duration,
	predicate func([]IngestRecord) bool,
) []IngestRecord

WaitForIngests waits until the ingest marker file satisfies the predicate.

func (*Harness) WaitForStates 

func (h *Harness) WaitForStates(t testing.TB, timeout time.Duration, predicate func([]StateRecord) bool) []StateRecord

WaitForStates waits until the state marker file satisfies the predicate.

type HarnessConfig 

type HarnessConfig struct {
	ExtensionDir             string
	ExtensionName            string
	DisplayName              string
	Platform                 string
	RoutingPolicy            bridgepkg.RoutingPolicy
	BoundSecrets             []subprocess.InitializeBridgeBoundSecret
	ManagedInstances         []ManagedInstanceConfig
	Driver                   session.AgentDriver
	StartTime                time.Time
	CrashOnceOnFirstDelivery bool
	BrokerOptions            []bridgepkg.DeliveryBrokerOption
	ExtraEnv                 map[string]string
}

HarnessConfig configures one subprocess-backed bridge adapter test harness.

type IngestRecord 

type IngestRecord struct {
	Envelope bridgepkg.InboundMessageEnvelope              `json:"envelope"`
	Result   extensioncontract.BridgesMessagesIngestResult `json:"result"`
	Error    string                                        `json:"error,omitempty"`
}

IngestRecord captures one fake inbound update mapped into a normalized ingest.

func WaitForIngestMarkers 

func WaitForIngestMarkers(
	t testing.TB,
	markers MarkerPaths,
	timeout time.Duration,
	predicate func([]IngestRecord) bool,
) []IngestRecord

WaitForIngestMarkers waits until the ingest marker file satisfies the predicate.

type ManagedInstanceConfig 

type ManagedInstanceConfig struct {
	ID             string
	DisplayName    string
	DMPolicy       bridgepkg.BridgeDMPolicy
	RoutingPolicy  bridgepkg.RoutingPolicy
	ProviderConfig map[string]any
	BoundSecrets   []subprocess.InitializeBridgeBoundSecret
}

ManagedInstanceConfig configures one provider-owned bridge instance created by the harness.

type ManagedInstanceExpectation 

type ManagedInstanceExpectation struct {
	InstanceID          string
	ExtensionName       string
	BoundSecretNames    []string
	ExpectedFinalStatus bridgepkg.BridgeStatus
}

ManagedInstanceExpectation describes one provider-owned bridge instance that must appear in the negotiated runtime and conformance evidence.

type ManagedInstanceOutcome 

type ManagedInstanceOutcome struct {
	InstanceID        string
	FinalStatus       bridgepkg.BridgeStatus
	DegradationReason bridgepkg.BridgeDegradationReason
}

ManagedInstanceOutcome summarizes the final state observed for one managed instance.

type MarkerPaths 

type MarkerPaths struct {
	Handshake string
	Ownership string
	State     string
	Delivery  string
	Ingest    string
	Updates   string
	Starts    string
	Shutdown  string
	CrashOnce string
}

MarkerPaths contains the standardized marker and control files used by the reference adapter and the conformance harness.

func NewMarkerPaths 

func NewMarkerPaths(root string) MarkerPaths

NewMarkerPaths returns a temp-root-relative marker layout used by the subprocess-backed adapter tests.

func NewTempMarkerPaths 

func NewTempMarkerPaths(t testing.TB) MarkerPaths

NewTempMarkerPaths keeps side-effect files under os.TempDir(), which is the boundary enforced by subprocess-backed reference adapters.

func (MarkerPaths) Env 

func (m MarkerPaths) Env() map[string]string

Env returns the environment expected by the reference adapter marker contract.

type OutcomeClass 

type OutcomeClass string

OutcomeClass identifies the classified recovery bucket validated by a scenario. 

const (
	OutcomeClassAuthFailure OutcomeClass = "auth_failure"
	OutcomeClassRateLimit   OutcomeClass = "rate_limit"
)

type OwnershipRecord 

type OwnershipRecord struct {
	Listed  []bridgepkg.BridgeInstance `json:"listed,omitempty"`
	Fetched []bridgepkg.BridgeInstance `json:"fetched,omitempty"`
	Error   string                     `json:"error,omitempty"`
}

OwnershipRecord captures the provider-owned instance list/get evidence collected by the reference adapter during boot.

type ProviderConformanceSummary 

type ProviderConformanceSummary struct {
	Provider         string
	Platform         string
	Targets          []CoverageTarget
	ManagedInstances []ManagedInstanceOutcome
}

ProviderConformanceSummary is the reusable matrix row future providers can extend.

func BuildConformanceMatrix 

func BuildConformanceMatrix(entries ...ProviderConformanceSummary) []ProviderConformanceSummary

BuildConformanceMatrix clones and canonicalizes provider summaries for reporting and validation.

func SummarizeConformanceReport 

func SummarizeConformanceReport(
	provider string,
	platform string,
	report ConformanceReport,
	targets ...CoverageTarget,
) ProviderConformanceSummary

SummarizeConformanceReport normalizes one provider report into a reusable matrix row.

type ScriptedPromptDriver 

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

ScriptedPromptDriver is a deterministic in-process session driver used by the adapter harness instead of a real ACP subprocess.

func NewScriptedPromptDriver 

func NewScriptedPromptDriver(now time.Time, script []ScriptedPromptEvent) *ScriptedPromptDriver

NewScriptedPromptDriver constructs a session driver that replays the provided agent events for every prompt.

func (*ScriptedPromptDriver) Cancel 

func (d *ScriptedPromptDriver) Cancel(context.Context, *session.AgentProcess) error

Cancel implements session.AgentDriver.

func (*ScriptedPromptDriver) Prompt 

func (d *ScriptedPromptDriver) Prompt(
	ctx context.Context,
	_ *session.AgentProcess,
	req acp.PromptRequest,
) (<-chan acp.AgentEvent, error)

Prompt implements session.AgentDriver.

func (*ScriptedPromptDriver) Start 

func (d *ScriptedPromptDriver) Start(_ context.Context, opts acp.StartOpts) (*session.AgentProcess, error)

Start implements session.AgentDriver.

func (*ScriptedPromptDriver) Stop 

func (d *ScriptedPromptDriver) Stop(_ context.Context, proc *session.AgentProcess) error

Stop implements session.AgentDriver.

type ScriptedPromptEvent 

type ScriptedPromptEvent struct {
	Type  string
	Text  string
	Error string
	Delay time.Duration
}

ScriptedPromptEvent is one deterministic agent event emitted by the harness driver when the host creates a session prompt.

type StateRecord 

type StateRecord struct {
	BridgeInstanceID string                   `json:"bridge_instance_id,omitempty"`
	Status           bridgepkg.BridgeStatus   `json:"status"`
	Instance         bridgepkg.BridgeInstance `json:"instance"`
	Error            string                   `json:"error,omitempty"`
}

StateRecord captures one adapter-driven `bridges/instances/report_state` result marker.

func WaitForStateMarkers 

func WaitForStateMarkers(
	t testing.TB,
	markers MarkerPaths,
	timeout time.Duration,
	predicate func([]StateRecord) bool,
) []StateRecord

WaitForStateMarkers waits until the state marker file satisfies the predicate.

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.