integration

type Adapter struct {
	orm.BaseModel `bun:"table:itg_adapter,alias:iad"`
	orm.FullAuditedModel

	SystemID   string `json:"systemId" bun:"system_id"`
	ContractID string `json:"contractId" bun:"contract_id"`
	// Direction selects the flow the script implements; an empty value is
	// normalized to outbound at save time.
	Direction Direction `json:"direction" bun:"direction"`
	Script    string    `json:"script" bun:"script"`
	// TimeoutMs overrides the script run timeout for this adapter; zero
	// inherits vef.integration.run_timeout. The system's TimeoutMs bounds
	// individual HTTP calls — a different axis.
	TimeoutMs int  `json:"timeoutMs" bun:"timeout_ms"`
	IsEnabled bool `json:"isEnabled" bun:"is_enabled"`
}

type Contract struct {
	orm.BaseModel `bun:"table:itg_contract,alias:ic"`
	orm.FullAuditedModel

	Code        string  `json:"code" bun:"code"`
	Name        string  `json:"name" bun:"name"`
	Description *string `json:"description" bun:"description,nullzero"`
	// Labels are host-owned selection metadata (e.g. which business scenes may
	// offer this contract for dynamic binding); the engine stores and filters
	// them but never interprets them. Key charset and sizes are enforced by
	// ValidateContract at save time.
	Labels map[string]string `json:"labels,omitempty" bun:"labels,type:jsonb,nullzero"`
	// InputSchema is the self-contained JSON Schema (draft 2020-12) the
	// invocation input is validated against; empty skips input validation.
	InputSchema json.RawMessage `json:"inputSchema" bun:"input_schema,type:jsonb,nullzero"`
	// OutputSchema is the self-contained JSON Schema the adapter script's
	// return value is validated against; empty skips output validation.
	OutputSchema json.RawMessage `json:"outputSchema" bun:"output_schema,type:jsonb,nullzero"`
	IsEnabled    bool            `json:"isEnabled" bun:"is_enabled"`
}

type DataSourceConfig struct {
	Kind config.DBKind `json:"kind"`
	// Mode gates script write access to this database; empty means read-only.
	Mode        DataSourceMode `json:"mode,omitempty"`
	Host        string         `json:"host,omitempty"`
	Port        uint16         `json:"port,omitempty"`
	User        string         `json:"user,omitempty"`
	Password    string         `json:"password,omitempty"`
	Database    string         `json:"database,omitempty"`
	Schema      string         `json:"schema,omitempty"`
	Path        string         `json:"path,omitempty"`
	SSLMode     config.SSLMode `json:"sslMode,omitempty"`
	SSLRootCert string         `json:"sslRootCert,omitempty"`
}

type DataSourceMode string

type Direction string

type FailureKind string

type HTTPExchange struct {
	Method          string            `json:"method"`
	URL             string            `json:"url"`
	RequestHeaders  map[string]string `json:"requestHeaders,omitempty"`
	RequestBody     string            `json:"requestBody,omitempty"`
	Status          int               `json:"status,omitempty"`
	ResponseHeaders map[string]string `json:"responseHeaders,omitempty"`
	ResponseBody    string            `json:"responseBody,omitempty"`
	DurationMs      int64             `json:"durationMs"`
	Error           string            `json:"error,omitempty"`
}

type InboundAuthConfig struct {
	Scheme string            `json:"scheme"`
	Params map[string]string `json:"params,omitempty"`
	// Script is the custom verification body for the "script" scheme: it runs
	// in a runtime with no IO capabilities, sees request and params, and
	// grants access by returning a truthy value.
	Script string `json:"script,omitempty"`
}

type InboundAuthScheme interface {
	// Name identifies the scheme referenced by a system's inboundAuth.scheme.
	Name() string
	// Verify authenticates the request against the system's inbound auth
	// configuration. The config arrives with sensitive parameters decrypted;
	// their values must never be logged. Any returned error denies the
	// delivery — its message stays server-side and is never echoed to the
	// caller.
	Verify(ctx context.Context, req *InboundRequest, auth *InboundAuthConfig) error
	// SensitiveParams names the parameters whose values are stored encrypted
	// and masked in management API responses; the SensitiveAll wildcard marks
	// every parameter sensitive.
	SensitiveParams() []string
}

type InboundHandler interface {
	// Contract returns the code of the contract the handler serves.
	Contract() string
	// Handle processes one schema-validated dispatch and returns the standard
	// output. A returned error is classified as FailureHandler; adapter
	// scripts may catch it to shape the external-facing reply.
	Handle(ctx context.Context, input any) (any, error)
}

type InboundRequest struct {
	SystemCode   string
	ContractCode string
	// Protocol names the gateway that received the call (e.g. "http").
	Protocol string
	Method   string
	Path     string
	Headers  map[string]string
	Query    map[string]string
	// Body is the raw request payload.
	Body []byte
	// ClientAddr is the network peer address, for IP-based verification.
	ClientAddr string
}

type InvocationLog struct {
	orm.BaseModel `bun:"table:itg_invocation_log,alias:il"`
	orm.CreationAuditedModel

	SystemCode   string `json:"systemCode" bun:"system_code"`
	ContractCode string `json:"contractCode" bun:"contract_code"`
	// Direction records which flow produced the entry: outbound invocations
	// or inbound deliveries.
	Direction Direction `json:"direction" bun:"direction"`
	// FailureKind is empty for a successful invocation.
	FailureKind FailureKind     `json:"failureKind" bun:"failure_kind"`
	DurationMs  int64           `json:"durationMs" bun:"duration_ms"`
	Input       json.RawMessage `json:"input" bun:"input,type:jsonb,nullzero"`
	Output      json.RawMessage `json:"output" bun:"output,type:jsonb,nullzero"`
	HTTPTrace   []HTTPExchange  `json:"httpTrace" bun:"http_trace,type:jsonb,nullzero"`
	Error       *string         `json:"error" bun:"error,nullzero"`
	RequestID   string          `json:"requestId" bun:"request_id"`
}

type InvocationStats struct {
	System        string                `json:"system"`
	Contract      string                `json:"contract"`
	Direction     Direction             `json:"direction"`
	Calls         int64                 `json:"calls"`
	Successes     int64                 `json:"successes"`
	Failures      map[FailureKind]int64 `json:"failures,omitempty"`
	AvgDurationMs int64                 `json:"avgDurationMs"`
	MaxDurationMs int64                 `json:"maxDurationMs"`
	LastError     string                `json:"lastError,omitempty"`
	LastErrorAt   time.Time             `json:"lastErrorAt,omitzero"`
}

type InvokeConfig struct {
	// SystemCode targets a system directly, bypassing route resolution.
	SystemCode string
	// RouteKey selects the system through the RouteResolver; empty is the
	// default route.
	RouteKey string
	// Timeout overrides the adapter/system call timeout when positive.
	Timeout time.Duration
	// CacheTTL caches the validated output for the given duration when
	// positive; invocations are never cached otherwise.
	CacheTTL time.Duration
}

type InvokeOption func(*InvokeConfig)

type Invoker interface {
	// Invoke executes the named contract with input against the system
	// selected by WithSystem, or resolved through the RouteResolver from the
	// WithRoute key (no target option resolves the empty route key, i.e. the
	// default route). The input is validated against the contract's input
	// schema before the script runs and the script's return value against
	// the output schema after, so the Result always carries a valid standard
	// model.
	Invoke(ctx context.Context, contract string, input any, opts ...InvokeOption) (*Result, error)
}

type OutboundAuthConfig struct {
	Scheme string            `json:"scheme"`
	Params map[string]string `json:"params,omitempty"`
	// Script is the custom signing body for the "script" scheme: it runs per
	// request in a runtime with no IO capabilities, sees the built request and
	// the decrypted params, and returns the credential headers to add.
	Script string `json:"script,omitempty"`
}

type OutboundAuthScheme interface {
	// Name identifies the scheme referenced by a system's outboundAuth.scheme.
	Name() string
	// Apply validates cfg and returns the client options implementing the
	// scheme. Cfg is never nil and its params arrive decrypted; sensitive
	// values must never be logged.
	Apply(cfg *OutboundAuthConfig) ([]httpx.Option, error)
	// SensitiveParams names the parameters whose values are stored encrypted
	// and masked in management API responses; the SensitiveAll wildcard marks
	// every parameter sensitive.
	SensitiveParams() []string
}

type OutboundEnvelopeConfig struct {
	// Request is the wrap script: it receives the request the adapter issued
	// as `request` ({ method, path, headers, query, body }) and returns the
	// request to put on the wire — fields it omits keep the adapter's values.
	Request string `json:"request,omitempty"`
	// Response is the unwrap script: it receives the completed HTTP response
	// as `response` (the fetch Response shape) and whatever it returns is
	// what the adapter's call yields — typically the payload stripped of the
	// vendor envelope. Vendor-level error codes belong here: throw
	// errors.upstream(msg) to classify the failure as upstream once for the
	// whole system.
	Response string `json:"response,omitempty"`
}

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

type RetryPolicy struct {
	// MaxAttempts is the total number of attempts, the first call included.
	MaxAttempts int `json:"maxAttempts"`
	// InitialBackoffMs is the base delay before the first retry; zero applies
	// the httpx default.
	InitialBackoffMs int64 `json:"initialBackoffMs,omitempty"`
	// MaxBackoffMs caps the delay between attempts; zero applies the httpx
	// default.
	MaxBackoffMs int64 `json:"maxBackoffMs,omitempty"`
}

type Route struct {
	orm.BaseModel `bun:"table:itg_route,alias:irt"`
	orm.FullAuditedModel

	RouteKey   string `json:"routeKey" bun:"route_key"`
	ContractID string `json:"contractId" bun:"contract_id"`
	SystemID   string `json:"systemId" bun:"system_id"`
	IsEnabled  bool   `json:"isEnabled" bun:"is_enabled"`
}

type RouteDiagnostics struct {
	Findings []RouteFinding `json:"findings"`
}

type RouteFinding struct {
	Kind         RouteFindingKind `json:"kind"`
	RouteID      string           `json:"routeId,omitempty"`
	RouteKey     string           `json:"routeKey"`
	ContractCode string           `json:"contractCode,omitempty"`
	ContractName string           `json:"contractName,omitempty"`
	SystemCode   string           `json:"systemCode,omitempty"`
	SystemName   string           `json:"systemName,omitempty"`
}

type RouteFindingKind string

type RouteResolver interface {
	// Resolve returns the code of the system serving contract for routeKey.
	// A key matching no rule fails with ErrRouteNotFound.
	Resolve(ctx context.Context, contract, routeKey string) (string, error)
}

type StatsInspector interface {
	// Stats returns a snapshot of invocation statistics, one entry per
	// (system, contract, direction) tuple observed since process start,
	// ordered by system, contract, then direction.
	Stats() []InvocationStats
}

type System struct {
	orm.BaseModel `bun:"table:itg_system,alias:isy"`
	orm.FullAuditedModel

	Code    string `json:"code" bun:"code"`
	Name    string `json:"name" bun:"name"`
	BaseURL string `json:"baseUrl" bun:"base_url"`
	// OutboundAuth selects how the framework authenticates against this
	// system's HTTP endpoints; nil sends requests unauthenticated.
	OutboundAuth *OutboundAuthConfig `json:"outboundAuth" bun:"outbound_auth,type:jsonb,nullzero"`
	// OutboundEnvelope wraps every outbound HTTP call of the system in its
	// common wire structure, so adapter scripts translate business payloads
	// only; nil sends adapter requests untouched.
	OutboundEnvelope *OutboundEnvelopeConfig `json:"outboundEnvelope" bun:"outbound_envelope,type:jsonb,nullzero"`
	// InboundAuth selects how calls arriving on this system's inbound
	// endpoints are proven to originate from the system itself; a system
	// without it refuses inbound delivery entirely (fail closed — the "none"
	// scheme opens it up deliberately).
	InboundAuth *InboundAuthConfig `json:"inboundAuth" bun:"inbound_auth,type:jsonb,nullzero"`
	// DataSource is the system's direct database connection (external views /
	// exchange tables). Its password is stored encrypted and masked in
	// management API responses.
	DataSource *DataSourceConfig `json:"dataSource" bun:"data_source,type:jsonb,nullzero"`
	// Params are non-sensitive, system-specific values (branch codes,
	// version flags) exposed to adapter scripts as system.params.
	Params map[string]string `json:"params" bun:"params,type:jsonb,nullzero"`
	// TimeoutMs bounds each HTTP call against the system; zero applies the
	// framework default.
	TimeoutMs int          `json:"timeoutMs" bun:"timeout_ms"`
	Retry     *RetryPolicy `json:"retry" bun:"retry,type:jsonb,nullzero"`
	IsEnabled bool         `json:"isEnabled" bun:"is_enabled"`
}