remote

Documentation

Overview

Package remote supplies request/response mapping and an opt-in cache for ordinary typed custom handlers that invoke an HTTP endpoint or MCP tool.

The mapper plans explicit request and response mappings and invokes a borrowed HTTP or MCP client. A typed const configuration selects the protocol. When caching is enabled, a separately bound xdatly/cache.Provider resolves an explicitly named backend; the mapper owns no cached values. Input paths use compiled transform selectors, response paths use RFC 6901 pointers, and Bindly assigns typed output fields. The mapper constructs or closes no transport clients or cache backends.

Index

• Constants
• type Cache
• type ClientOptions
  • func (o *ClientOptions) Validate() error
• type Config
  • func DecodeConfig(data []byte) (*Config, error)
• type Credential
• type Mapper
  • func NewMapper(options ...Option) *Mapper
  • func (m *Mapper) CachedEntries(ctx context.Context, config *Config, provider xcache.Provider) (int, error)
  • func (m *Mapper) HTTP(ctx context.Context, config *Config, provider xhttp.Provider, ...) error
  • func (m *Mapper) Invalidate(ctx context.Context, config *Config, provider xcache.Provider, ...) (int, error)
  • func (m *Mapper) MCP(ctx context.Context, config *Config, provider xmcp.Provider, ...) error
• type Option
  • func WithClock(clock func() time.Time) Option
  • func WithResources(resources fs.FS) Option
• type RequestMapping
• type Response
• type ResponseMapping
• type StatusError
  • func (e *StatusError) Error() string
• type ToolError
  • func (e *ToolError) Error() string
• type Validity

Constants

const (
	// TransportHTTP invokes one HTTP endpoint through an injected xhttp.Provider.
	TransportHTTP = "http"
	// TransportMCP calls one MCP tool through an injected xmcp.Provider.
	TransportMCP = "mcp"

	// SourceJSON decodes an HTTP response body as one JSON document.
	SourceJSON = "json"
	// SourceStructuredContent uses CallToolResult.StructuredContent as the document.
	SourceStructuredContent = "structuredContent"
	// SourceText decodes the concatenated MCP text content as a JSON document.
	SourceText = "text"

	// ValidityUnix reads an absolute expiry as seconds since the Unix epoch.
	ValidityUnix = "unix"
	// ValidityRFC3339 reads an absolute expiry as an RFC 3339 string.
	ValidityRFC3339 = "rfc3339"
	// ValiditySeconds reads a relative lifetime in seconds.
	ValiditySeconds = "seconds"
)

Types

type Cache

type Cache struct {
	Name      string   `json:"name"`
	TTL       string   `json:"ttl"`
	Partition []string `json:"partition,omitempty"`
}

Cache opts into an explicitly registered named backend. Backend capacity is configured when the cache is registered, not per remote declaration. Keys include the configuration and mapped request values; Partition adds server-owned values such as a verified principal or tenant.

type ClientOptions

type ClientOptions struct {
	Transport string         `json:"transport"`
	HTTP      *xhttp.Options `json:"http,omitempty"`
	MCP       *xmcp.Options  `json:"mcp,omitempty"`
}

ClientOptions selects exactly one configured protocol. Transport names the protocol; the matching section carries the public xdatly options that are handed, unchanged, to the injected provider of that protocol. It is deployment metadata bound with kind=const, never a caller value.

func (*ClientOptions) Validate

func (o *ClientOptions) Validate() error

Validate checks the structural declaration the handler depends on for its request mapping: one protocol section, an absolute endpoint, a supported method or a tool name, unique canonical header names and well-formed limits. Zero or omitted limits mean unlimited.

type Config

type Config struct {
	Client ClientOptions `json:"client"`
	// Request maps component input paths onto the outbound call.
	Request []RequestMapping `json:"request,omitempty"`
	// Response maps response document paths onto the declared output.
	Response Response `json:"response"`
	// Credential attaches one server-resolved secret to the call.
	Credential *Credential `json:"credential,omitempty"`
	// Cache enables explicit result caching; absent means no caching.
	Cache *Cache `json:"cache,omitempty"`
}

Config is the complete handler declaration: the selected client options plus the explicit request/response mappings and cache policy. It is authored as component metadata and bound as one typed constant.

func DecodeConfig

func DecodeConfig(data []byte) (*Config, error)

DecodeConfig strictly decodes one configuration object. Applications that load declarations outside Datly's typed const binder can use this utility.

type Credential

type Credential struct {
	Resource string `json:"resource"`
	Header   string `json:"header,omitempty"`
	Argument string `json:"argument,omitempty"`
}

Credential attaches one server-resolved secret read from the configured resource store. Its content is forwarded unchanged (include any scheme in the stored value) as the named header, or as an MCP tool argument when the remote API is explicitly argument-based. Caller inputs are forwarded through RequestMapping instead, never through Credential.

type Mapper

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

Mapper is the shared request/response mapping and result-cache helper an ordinary custom handler calls from Exec. It receives the configuration, the selected provider and the typed input/output explicitly; it discovers no fields, binds no dependencies and owns no clients. One Mapper may serve any number of handlers; compiled plans and cache entries are scoped by configuration identity and by the concrete input/output types.

func NewMapper

func NewMapper(options ...Option) *Mapper

NewMapper builds a helper with no backend. Enabled declarations resolve a named cache from the ordinary handler's bound xcache.Provider.

func (*Mapper) CachedEntries

func (m *Mapper) CachedEntries(ctx context.Context, config *Config, provider xcache.Provider) (int, error)

CachedEntries reconciles locally tracked keys against the named backend.

func (*Mapper) HTTP

func (m *Mapper) HTTP(ctx context.Context, config *Config, provider xhttp.Provider, cacheProvider xcache.Provider, input, output any) error

HTTP maps input onto the configured HTTP request, executes it through the client the provider resolves for config.Client.HTTP, and maps the JSON response into output. input and output must be non-nil struct pointers; mapping paths are resolved against their types. config must select transport "http".

func (*Mapper) Invalidate

func (m *Mapper) Invalidate(ctx context.Context, config *Config, provider xcache.Provider, partition ...string) (int, error)

Invalidate fences in-flight results and deletes one partition in a named backend. No partition values clears all entries tracked by this Mapper.

func (*Mapper) MCP

func (m *Mapper) MCP(ctx context.Context, config *Config, provider xmcp.Provider, cacheProvider xcache.Provider, input, output any) error

MCP maps input onto the configured tool call, executes it through the client the provider resolves for config.Client.MCP, and maps the selected result document into output. config must select transport "mcp".

type Option

type Option func(*Mapper)

Option configures a Mapper.

func WithClock

func WithClock(clock func() time.Time) Option

WithClock replaces the cache clock; tests use it for deterministic expiry.

func WithResources

func WithResources(resources fs.FS) Option

WithResources supplies the server-owned store that resolves credential.resource references. Without it, credential declarations fail.

type RequestMapping

type RequestMapping struct {
	Input    string  `json:"input"`
	Header   string  `json:"header,omitempty"`
	Query    string  `json:"query,omitempty"`
	Path     string  `json:"path,omitempty"`
	Body     *string `json:"body,omitempty"`
	Argument string  `json:"argument,omitempty"`
}

RequestMapping copies one input value, unchanged, onto exactly one request target. Input is a compiled transform selector path over the component input struct (for example Token or Scope.Tenant). Header forwards the value as the named outgoing header (the conventional pairing is an input bound from header/Authorization forwarded as Authorization). Body is a JSON Pointer inside the JSON object body; "" selects the whole body. Argument names one MCP tool argument.

type Response

type Response struct {
	// Source selects the document: json (HTTP), structuredContent or text (MCP).
	Source   string            `json:"source,omitempty"`
	Mappings []ResponseMapping `json:"mappings"`
	// Validity reads an explicit expiry from the document and caps cache TTL.
	Validity *Validity `json:"validity,omitempty"`
}

Response declares how the remote document populates the output contract.

type ResponseMapping

type ResponseMapping struct {
	Path     string `json:"path"`
	Output   string `json:"output"`
	Optional bool   `json:"optional,omitempty"`
}

ResponseMapping copies one JSON Pointer location of the response document into one output selector path. A missing or null location fails unless the mapping is optional.

type StatusError

type StatusError struct {
	Method     string
	URL        string
	StatusCode int
}

StatusError reports a non-2xx remote HTTP response without echoing its body.

func (*StatusError) Error

func (e *StatusError) Error() string

type ToolError

type ToolError struct {
	Tool    string
	URL     string
	Message string
}

ToolError reports a tool-level failure (isError=true) as distinct from a protocol or transport failure.

func (*ToolError) Error

func (e *ToolError) Error() string

type Validity

type Validity struct {
	Path   string `json:"path"`
	Format string `json:"format"`
}

Validity locates an explicit expiry inside the response document.