runtimeharpoon

package
v0.0.14 Latest Latest
Warning

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

 Go to latest Published: Sep 1, 2026 License: Apache-2.0 Imports: 43 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	RedirectMismatchSchemeHTTPToHTTPS = redirectMismatchSchemeHTTPToHTTPS
	RedirectMismatchSchemeHTTPSToHTTP = redirectMismatchSchemeHTTPSToHTTP
	RedirectMismatchPath              = redirectMismatchPath
	RedirectMismatchQuery             = redirectMismatchQuery
	RedirectMismatchHost              = redirectMismatchHost
	RedirectMismatchOther             = redirectMismatchOther
)
View Source 
const MaxContentTypeLogBytes = maxContentTypeLogBytes

MaxContentTypeLogBytes is the byte bound used for receipt content types.

Variables

View Source 
var Module = fx.Module(
	"harpoon",
	fx.Provide(newHarpoonService, newRegistryCounter, newHarpoonGuardedMux, NewHostBusSubscriber, NewHostBus, NewStartupCatalogDigestState),
	fx.Invoke(registerAdditionalTransport, StartHostRegistration, StartCatalogDigestLogging),
)

Module wires the harpoon MCP server.

Functions

func BuildHarpoonHTTPEndpoint 

func BuildHarpoonHTTPEndpoint(healthCfg *runtimeconfig.HealthConfig, svc runtimehealth.Service, timeout time.Duration) string

BuildHarpoonHTTPEndpoint resolves the operator-facing streamable endpoint.

func FilterOutboundHeaders 

func FilterOutboundHeaders(headers map[string]string) (http.Header, int, []string)

FilterOutboundHeaders applies the core outbound-header policy.

func IsBlockedOutboundHeader 

func IsBlockedOutboundHeader(headerName string) bool

IsBlockedOutboundHeader reports whether a caller-supplied header is blocked.

func NewGuardedMux 

func NewGuardedMux(adminMux *http.ServeMux) httpguard.GuardedMux

NewGuardedMux creates the loopback-only Harpoon HTTP transport mux.

func NewHostBus 

func NewHostBus(p HostBusSubscriberIn) (hostbus.HostRegistrationBus, error)

NewHostBus constructs the canonical host-registration bus.

func NewRestartableInMemoryTransport 

func NewRestartableInMemoryTransport(ctx context.Context, server *mcp.Server, logger *slog.Logger) mcp.Transport

NewRestartableInMemoryTransport creates the shared reconnectable in-memory transport used by both runtime and package-owned adapters.

func NewStartupCatalogDigestState added in v0.0.14 

func NewStartupCatalogDigestState() *startupCatalogDigestState

NewStartupCatalogDigestState constructs the internal Fx-shared startup digest holder. It is exported only so the full-client adapter can provide the same runtime-owned state without exposing its contents.

func NormalizeToken 

func NormalizeToken(value string) string

NormalizeToken exposes the canonical metadata-token normalization for full-client extension tools without duplicating it.

func RegisterAdditionalTransport 

func RegisterAdditionalTransport(p AdditionalTransportParams) error

RegisterAdditionalTransport owns the common HTTP streamable transport registration for both runtime and full-client Harpoon graphs.

func RegisterHostBundleForConfig 

func RegisterHostBundleForConfig(bundle hostbus.URLBundle, cfg runtimeconfig.HarpoonHostClassifierConfig, registry *Registry, logger *slog.Logger) error

RegisterHostBundleForConfig applies one discovered URL bundle using the canonical runtime classifier. It is primarily a compatibility seam for full-client tests and adapters that must not duplicate registration logic.

func ResponseContentTypeForLog 

func ResponseContentTypeForLog(contentType string) string

ResponseContentTypeForLog returns the normalized bounded content type used in call receipts.

func StartCatalogDigestLogging added in v0.0.14 

func StartCatalogDigestLogging(p startupCatalogDigestLifecycleParams) error

StartCatalogDigestLogging waits for the stricter startup-only Harpoon catalog barrier, then emits exactly one digest event for this process. It deliberately does not subscribe to later registry mutations.

func StartHostRegistration 

func StartHostRegistration(p HostRegistrationParams) error

StartHostRegistration wires canonical OAuth host auto-registration.

func TransformHeaders 

func TransformHeaders(headers http.Header, rewriter *URLRewriter) (http.Header, bool)

TransformHeaders rewrites allowlisted URLs in response headers.

func TransformJSONBody 

func TransformJSONBody(body []byte, rewriter *URLRewriter) ([]byte, bool)

TransformJSONBody rewrites allowlisted URLs in a JSON response body.

Types

type AdditionalTransportParams 

type AdditionalTransportParams struct {
	Lifecycle  fx.Lifecycle
	GuardedMux httpguard.GuardedMux
	Config     *runtimeconfig.HarpoonConfig
	Server     MCPServerProvider
	Logger     *slog.Logger
}

AdditionalTransportParams contains the shared inputs for registering the optional loopback-only HTTP streamable Harpoon transport.

type CallEvent 

type CallEvent struct {
	Label                   string
	URL                     string
	Method                  string
	Status                  int
	RequestBody             string
	RequestBytes            int
	ResponseBytes           int
	Error                   string
	StartedAt               time.Time
	ResponseContentType     string
	ResponseBody            []byte
	ResponseBodyTransformed []byte
}

CallEvent is the transport-neutral receipt emitted after a call_target attempt. Optional adapters can observe it without changing core routing.

type CallObserver 

type CallObserver func(CallEvent)

CallObserver receives one receipt after a call_target attempt.

type CallTargetRequest 

type CallTargetRequest = callTargetRequest

Exported aliases keep the shared core reusable by thin adapters while the runtime entrypoint continues to expose only its approved command surface.

type CallTargetResponse 

type CallTargetResponse = callTargetResponse

type HostBusSubscriberIn 

type HostBusSubscriberIn struct {
	fx.In

	Subscriber chan hostbus.URLBundle `name:"harpoon_hostbus_subscriber"`
}

HostBusSubscriberIn consumes the named URL-bundle subscriber.

type HostBusSubscriberOut 

type HostBusSubscriberOut struct {
	fx.Out

	Subscriber chan hostbus.URLBundle `name:"harpoon_hostbus_subscriber"`
}

HostBusSubscriberOut provides the named URL-bundle subscriber used by both runtime and full-client Harpoon Fx graphs.

func NewHostBusSubscriber 

func NewHostBusSubscriber() HostBusSubscriberOut

NewHostBusSubscriber creates the bounded named subscriber channel.

type HostRegistrationParams 

type HostRegistrationParams struct {
	fx.In

	Lifecycle      fx.Lifecycle
	Logger         *slog.Logger
	Registry       *Registry
	Config         *runtimeconfig.HarpoonConfig
	ControlPlane   *runtimeconfig.ControlPlaneConfig `optional:"true"`
	DigestState    *startupCatalogDigestState        `optional:"true"`
	StartupCatalog *hostbus.StartupCatalogState      `optional:"true"`
	Bus            hostbus.HostRegistrationBus
	Subscriber     chan hostbus.URLBundle `name:"harpoon_hostbus_subscriber"`
}

HostRegistrationParams contains the shared dependencies for OAuth-discovered Harpoon target registration.

type ListTargetsRequest 

type ListTargetsRequest = listTargetsRequest

type ListTargetsResponse 

type ListTargetsResponse = listTargetsResponse

type MCPServerProvider 

type MCPServerProvider interface {
	MCPServer() *mcp.Server
}

MCPServerProvider is the narrow contract needed by shared Harpoon wiring. Full-client adapters can add tools and call observers without duplicating registry, transport, lifecycle, or route-log behavior.

type RedirectMismatchDetails 

type RedirectMismatchDetails = redirectMismatchDetails

Exported aliases let thin adapters preserve their existing package-local names without copying registry behavior.

type RedirectMismatchKind 

type RedirectMismatchKind = redirectMismatchKind

type Registry 

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

Registry stores allowed targets keyed by label.

func NewRegistry 

func NewRegistry(logger *slog.Logger, allowPlaintext bool, targets []Target) (*Registry, error)

NewRegistry constructs a registry seeded with the provided targets and a default limit.

func NewRegistryWithLimit 

func NewRegistryWithLimit(logger *slog.Logger, allowPlaintext bool, targets []Target, limit int) (*Registry, error)

NewRegistryWithLimit constructs a registry with a maximum number of targets.

func (*Registry) AllowsURL 

func (r *Registry) AllowsURL(candidate *url.URL) bool

AllowsURL reports whether the URL exactly matches any registered target after normalization.

func (*Registry) Count 

func (r *Registry) Count() int

Count reports the number of registered targets.

func (*Registry) ExactURL 

func (r *Registry) ExactURL(label string) (*url.URL, bool)

ExactURL returns the pre-normalization URL for a registered target. Thin adapters use this for capabilities whose protocol contract requires exact URL spelling rather than the normalized routing form.

func (*Registry) ExplainBlockedRedirect 

func (r *Registry) ExplainBlockedRedirect(candidate *url.URL) *redirectMismatchDetails

ExplainBlockedRedirect classifies why a redirect target missed the allow list.

func (*Registry) Lookup 

func (r *Registry) Lookup(label string) (Target, bool)

Lookup returns the target for a label.

func (*Registry) RegisterTarget 

func (r *Registry) RegisterTarget(target Target) error

RegisterTarget adds a target to the registry after validation.

func (*Registry) Resolve 

func (r *Registry) Resolve(label string) (*url.URL, error)

Resolve returns the target URL for a label.

func (*Registry) SummarizeTargets 

func (r *Registry) SummarizeTargets() []map[string]string

SummarizeTargets returns a stable, log-friendly projection of targets.

func (*Registry) TargetForURL 

func (r *Registry) TargetForURL(candidate *url.URL) (Target, bool)

TargetForURL returns the configured target whose URL exactly matches candidate.

func (*Registry) Targets 

func (r *Registry) Targets() []Target

Targets returns a copy of the registered targets in registration order.

func (*Registry) WaitForTarget 

func (r *Registry) WaitForTarget(ctx context.Context, label string) (Target, error)

WaitForTarget blocks until a target with the provided label is registered or ctx expires.

type RegistryCounter 

type RegistryCounter interface {
	Count() int
}

RegistryCounter is the minimal cross-package contract needed by polling and dispatch code to decide whether the Harpoon channel is routable.

type Server 

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

Server provides MCP tools for constrained HTTP access.

func NewServer 

func NewServer(cfg *runtimeconfig.HarpoonConfig, registry *Registry, logger *slog.Logger, opts ...ServerOption) (*Server, error)

NewServer constructs a harpoon MCP server.

func (*Server) CallTarget 

func (s *Server) CallTarget(ctx context.Context, params CallTargetRequest) (*CallTargetResponse, error)

CallTarget performs one constrained outbound call. It is exported so package-owned adapters can reuse the core without copying request logic.

func (*Server) ListTargets 

func (s *Server) ListTargets(params ListTargetsRequest) ListTargetsResponse

ListTargets returns the filtered target inventory.

func (*Server) MCPServer 

func (s *Server) MCPServer() *mcp.Server

MCPServer builds an MCP server with harpoon tools registered.

func (*Server) UnixTransportCount 

func (s *Server) UnixTransportCount() int

UnixTransportCount reports the number of cached Unix-socket transports.

type ServerOption 

type ServerOption func(*serverOptions)

ServerOption configures optional server behavior.

func WithCallObserver 

func WithCallObserver(observer CallObserver) ServerOption

WithCallObserver adds a package-owned call receipt observer. The runtime binary does not install any optional observers.

func WithHTTPTransport 

func WithHTTPTransport(rt http.RoundTripper) ServerOption

WithHTTPTransport sets the HTTP transport used for Harpoon outbound calls.

func WithInstructions 

func WithInstructions(instructions string) ServerOption

WithInstructions overrides the default MCP server instructions.

func WithMeter 

func WithMeter(meter metric.Meter) ServerOption

WithMeter configures the meter used for Harpoon metrics.

func WithToolRegistrar 

func WithToolRegistrar(registrar ToolRegistrar) ServerOption

WithToolRegistrar adds a package-owned tool registration hook. The runtime binary does not install any optional hooks.

type ServiceFactory 

type ServiceFactory func(*Registry, *slog.Logger, []ServerOption) (MCPServerProvider, error)

ServiceFactory constructs the flavor-specific MCP server over the shared registry and transport options.

type SharedServiceOutputs 

type SharedServiceOutputs struct {
	Registry         *Registry
	HarpoonTransport mcp.Transport
}

SharedServiceOutputs contains the common outputs produced for either Harpoon flavor.

func NewSharedService 

func NewSharedService(p SharedServiceParams) (SharedServiceOutputs, error)

NewSharedService owns the common Harpoon registry, outbound transport, route logging, lifecycle, and in-memory MCP transport wiring.

type SharedServiceParams 

type SharedServiceParams struct {
	Lifecycle                fx.Lifecycle
	Logger                   *slog.Logger
	MeterProvider            *sdkmetric.MeterProvider
	Config                   *runtimeconfig.HarpoonConfig
	Health                   *runtimeconfig.HealthConfig
	HealthSvc                runtimehealth.Service
	TLSBundle                *tlsconfig.Bundle
	Registrars               []TargetRegistrar
	NewServer                ServiceFactory
	LegacyProtocolForTesting bool
}

SharedServiceParams contains the runtime-safe dependencies shared by the runtime and full-client Harpoon graphs.

type Target 

type Target struct {
	Label           string
	Description     string
	Category        string
	Source          string
	Tags            []string
	InclusionReason string
	BaseURL         *url.URL
	UnixSocketPath  string
	// contains filtered or unexported fields
}

Target describes a registered outbound HTTP target.

func ConvertTargets 

func ConvertTargets(targets []runtimeconfig.HarpoonTarget) []Target

ConvertTargets projects config targets into registered runtime targets.

type TargetInfo 

type TargetInfo = targetInfo

type TargetRegistrar 

type TargetRegistrar func(*Registry) error

TargetRegistrar allows programmatic target registration during startup.

func WithTarget 

func WithTarget(target Target) TargetRegistrar

WithTarget returns a registrar that registers the provided target.

type ToolRegistrar 

type ToolRegistrar func(*mcp.Server)

ToolRegistrar adds optional tools to a Harpoon MCP server without making the runtime core import the package that owns those tools.

type URLRewriter 

type URLRewriter = urlRewriter

URLRewriter is the shared URL transformation helper exposed to thin adapters without duplicating rewrite behavior.

func NewURLRewriter 

func NewURLRewriter(targets []Target) *URLRewriter

NewURLRewriter builds a shared URL transformation helper.

Source Files

View all Source files

Directories

Path Synopsis
internal
hostclassifier

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.