http

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Oct 16, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package http implements the registered workflow http@v1 step kind. Network resolution, destination authorization, dialing, secrets, artifacts, and operational observation remain explicit adapter boundaries.

Configuration is a closed graph.Config object. It requires an absolute http(s) "url" and accepts "method", "headers", JSON-compatible "body", opaque-reference "auth", "timeout", "max_response_bytes", "inline_limit", "expected_status", "expected_content_types", "expected_json_schema", "redirects", "idempotency_key", "effects", and "capabilities". Defaults are GET, 30 seconds, 8 MiB maximum response, 64 KiB inline capture, 2xx status, and no redirects. Kind.Spec returns the machine-readable schema.

Every resolved address of every hop is authorized before one deterministic address is pinned for the actual dial. Redirects are followed manually and never carry credentials across origins. Secret references are resolved only immediately before Transport.RoundTrip; their material is excluded from ConfigDescription, observations, outputs, and structured errors.

Completed results contain status, normalized headers, a string or artifact body, optional inline body_json, and sanitized final-request metadata. Large JSON never appears in body_json after promotion to an artifact.

Index

Constants

View Source 
const (
	KindName    = "http"
	KindVersion = "v1"

	OutputStatus   = "status"
	OutputHeaders  = "headers"
	OutputBody     = "body"
	OutputBodyJSON = "body_json"
	OutputMetadata = "request_metadata"
)

Variables

View Source 
var (
	ErrInvalidOptions = errors.New("invalid HTTP adapter options")
	ErrInvalidConfig  = errors.New("invalid HTTP step config")
	ErrPolicyDenied   = errors.New("HTTP destination denied")
	ErrInvalidResult  = errors.New("invalid HTTP response")
)

Functions

This section is empty.

Types

type ArtifactRequest 

type ArtifactRequest struct {
	Name     string
	Content  []byte
	Metadata values.Metadata
	RunID    string
	MaxBytes int64
}

ArtifactRequest contains one already-redacted response body. MaxBytes is the original configured response bound; sinks must not exceed it.

type ArtifactSink 

type ArtifactSink interface {
	CaptureArtifact(context.Context, ArtifactRequest) (values.Value, error)
}

ArtifactSink materializes large or binary response bodies.

type ArtifactSinkFunc 

type ArtifactSinkFunc func(context.Context, ArtifactRequest) (values.Value, error)

ArtifactSinkFunc adapts a function to ArtifactSink.

func (ArtifactSinkFunc) CaptureArtifact 

func (f ArtifactSinkFunc) CaptureArtifact(ctx context.Context, request ArtifactRequest) (values.Value, error)

type ConfigDescription 

type ConfigDescription struct {
	Method                string                `json:"method"`
	Origin                string                `json:"origin"`
	DeclaredEffects       graph.EffectSet       `json:"declared_effects,omitempty"`
	DeclaredCapabilities  []string              `json:"declared_capabilities,omitempty"`
	IdempotencyKeyPresent bool                  `json:"idempotency_key_present"`
	Policy                PolicyDescription     `json:"policy"`
	EffectiveEffects      graph.EffectSet       `json:"effective_effects"`
	EffectiveIdempotency  graph.IdempotencyMode `json:"effective_idempotency"`
	EffectiveRetrySafety  stepkind.RetrySafety  `json:"effective_retry_safety"`
}

ConfigDescription is the deterministic pre-execution policy contract. URL path/query, headers, body, credentials, and idempotency-key values are absent.

type ContextDialer 

type ContextDialer interface {
	DialContext(context.Context, string, string) (net.Conn, error)
}

ContextDialer is the narrow dial seam used by PinnedTransport.

type DestinationAuthorization 

type DestinationAuthorization struct {
	AllowMethodRewrite bool
}

DestinationAuthorization contains narrow trusted decisions that cannot be inferred safely from the author configuration alone.

type DestinationRequest 

type DestinationRequest struct {
	Scheme   string
	Host     string
	Port     uint16
	Address  netip.Addr
	Path     string
	Hop      int
	Method   string
	Redirect *RedirectContext
}

DestinationRequest is presented once for every resolved address of every hop. Host is normalized without brackets; Port is always explicit.

type Exchange 

type Exchange struct {
	Request     *nethttp.Request
	Destination DestinationRequest
}

Exchange is the process-local request handed to Transport. Request may contain resolved credentials. Transport implementations must dial exactly Destination.Address:Destination.Port and must not consult ambient proxies, credential stores, cookie jars, or a second DNS resolver.

type Kind 

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

Kind is the registered HTTP step-kind implementation.

func New 

func New(options Options) (*Kind, error)

New constructs http@v1. Policy is required: the adapter never supplies a permissive destination policy. Resolver and transport receive secure local defaults when omitted.

func Register 

func Register(registry stepkind.Registry, options Options) (*Kind, error)

Register constructs and registers http@v1.

func (*Kind) DescribeConfig 

func (k *Kind) DescribeConfig(ctx context.Context, input graph.Config) (ConfigDescription, error)

DescribeConfig returns the deterministic non-secret policy view. Only a coherent trusted description for a safe method can narrow the conservative immutable metadata.

func (*Kind) Execute 

func (k *Kind) Execute(ctx context.Context, invocation stepkind.PreparedInvocation) (stepkind.StepResult, error)

Execute performs exactly one exchange per authorized hop and never retries a transport failure transparently.

func (*Kind) Spec 

func (*Kind) Spec() stepkind.StepKindSpec

Spec returns fail-safe metadata for arbitrary HTTP requests. Trusted host policy may provide a narrower per-config description through DescribeConfig.

func (*Kind) ValidateConfig 

func (*Kind) ValidateConfig(ctx context.Context, input graph.Config) []diagnostic.Diagnostic

ValidateConfig reports deterministic adapter-specific findings without resolving DNS, policy, or secrets.

type Observation 

type Observation struct {
	Phase     ObservationPhase
	Origin    string
	Method    string
	Hop       int
	Status    int
	Headers   map[string][]string
	BodyBytes int64
	Code      string
}

Observation is operational metadata, never workflow output data. Origin has no path/query. Header values are already masked; body bytes are never present.

type ObservationPhase 

type ObservationPhase string

ObservationPhase is a closed operational event phase. 

const (
	ObservationRequest  ObservationPhase = "request"
	ObservationResponse ObservationPhase = "response"
	ObservationRedirect ObservationPhase = "redirect"
	ObservationError    ObservationPhase = "error"
)

type Observer 

type Observer interface {
	ObserveHTTP(context.Context, Observation) error
}

Observer receives defensive, sanitized operational observations. Errors are deliberately ignored and cannot change workflow execution.

type ObserverFunc 

type ObserverFunc func(context.Context, Observation) error

ObserverFunc adapts a function to Observer.

func (ObserverFunc) ObserveHTTP 

func (f ObserverFunc) ObserveHTTP(ctx context.Context, observation Observation) error

type Options 

type Options struct {
	Resolver  Resolver
	Policy    Policy
	Transport Transport
	Secrets   values.SecretResolver
	Artifacts ArtifactSink
	Observer  Observer
	// MaxHeaderBytes bounds both resolved request and received response headers.
	MaxHeaderBytes int64
}

Options injects every security- or persistence-sensitive boundary.

type PinnedTransport 

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

PinnedTransport is the default proxy-free, cookie-free, single-destination transport. Each RoundTrip owns a fresh net/http transport and connection.

func NewPinnedTransport 

func NewPinnedTransport(options PinnedTransportOptions) (*PinnedTransport, error)

NewPinnedTransport constructs the secure default transport.

func (*PinnedTransport) RoundTrip 

func (t *PinnedTransport) RoundTrip(ctx context.Context, exchange Exchange) (*nethttp.Response, error)

type PinnedTransportOptions 

type PinnedTransportOptions struct {
	Dialer                 ContextDialer
	TLSConfig              *tls.Config
	MaxResponseHeaderBytes int64
}

PinnedTransportOptions configures the secure default transport. TLSConfig is defensively cloned for each exchange; ServerName is always replaced by the approved logical host.

type Policy 

type Policy interface {
	DescribeRequest(context.Context, RequestDeclaration) (PolicyDescription, error)
	AuthorizeDestination(context.Context, DestinationRequest) (DestinationAuthorization, error)
}

Policy supplies both pre-execution metadata and per-address authorization. Returning nil from AuthorizeDestination means only that the destination is allowed; method rewriting still requires an explicit true decision.

type PolicyDescription 

type PolicyDescription struct {
	Trusted     bool                  `json:"trusted"`
	Effects     graph.EffectSet       `json:"effects,omitempty"`
	Idempotency graph.IdempotencyMode `json:"idempotency"`
	RetrySafety stepkind.RetrySafety  `json:"retry_safety"`
}

PolicyDescription is a host's pre-execution interpretation. Only a trusted, valid description may narrow the adapter's conservative metadata.

type RedirectContext 

type RedirectContext struct {
	Status         int
	PreviousOrigin string
	CrossOrigin    bool
	Method         string
	ProposedMethod string
	MethodRewrite  bool
}

RedirectContext describes one process-local redirect decision without the raw Location value or URL query.

type RedirectMode 

type RedirectMode string

RedirectMode controls whether the adapter can follow a redirect. Policy mode still requires destination authorization for every address of every hop; it is not an allow-by-configuration switch. 

const (
	RedirectDeny       RedirectMode = "deny"
	RedirectSameOrigin RedirectMode = "same_origin"
	RedirectPolicy     RedirectMode = "policy"
)

type RequestDeclaration 

type RequestDeclaration struct {
	Method            string          `json:"method"`
	Scheme            string          `json:"scheme"`
	Host              string          `json:"host"`
	Port              uint16          `json:"port"`
	Path              string          `json:"path"`
	Effects           graph.EffectSet `json:"effects,omitempty"`
	Capabilities      []string        `json:"capabilities,omitempty"`
	HasBody           bool            `json:"has_body"`
	HasSecretRefs     bool            `json:"has_secret_refs"`
	HasIdempotencyKey bool            `json:"has_idempotency_key"`
	RedirectMode      RedirectMode    `json:"redirect_mode"`
}

RequestDeclaration is the non-secret pre-execution policy view. Path never includes a query or fragment. Effects and capabilities are author claims, not effective permissions.

type Resolver 

type Resolver interface {
	LookupNetIP(context.Context, string, string) ([]netip.Addr, error)
}

Resolver resolves every address considered for a destination. Implementors must return all answers; the adapter authorizes every answer before choosing one canonical address to pin for the actual dial.

type Transport 

type Transport interface {
	RoundTrip(context.Context, Exchange) (*nethttp.Response, error)
}

Transport performs exactly one HTTP exchange. It must not transparently retry or follow redirects.

type TransportError 

type TransportError struct {
	Failure TransportFailure
	Cause   error
}

TransportError lets an injected transport retain a process-local cause while exposing only a stable category to persistence and retry policy.

func (*TransportError) Error 

func (e *TransportError) Error() string

func (*TransportError) Unwrap 

func (e *TransportError) Unwrap() error

type TransportFailure 

type TransportFailure string

TransportFailure is a stable failure category supplied by custom transports. 

const (
	FailureDNS      TransportFailure = "dns"
	FailureConnect  TransportFailure = "connect"
	FailureTLS      TransportFailure = "tls"
	FailureProtocol TransportFailure = "protocol"
	FailureTimeout  TransportFailure = "timeout"
	FailureCanceled TransportFailure = "canceled"
)

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.