retrieval

package
v0.7.2 Latest Latest
Warning

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

 Go to latest Published: Nov 20, 2025 License: Apache-2.0, MIT Imports: 32 Imported by: 8

Documentation

Index

Constants

View Source 
const MemoryDelegationCacheSize = 100

Variables

This section is empty.

Functions

func ExtractInvocation 

func ExtractInvocation(ctx context.Context, root ipld.Link, msg message.AgentMessage, cache delegation.Store) (invocation.Invocation, error)

func Handle 

func Handle(ctx context.Context, srv CachingServer, request transport.HTTPRequest) (transport.HTTPResponse, error)

Types

type AgentMessageInvocationCountError 

type AgentMessageInvocationCountError struct{}

func NewAgentMessageInvocationCountError 

func NewAgentMessageInvocationCountError() AgentMessageInvocationCountError

func (AgentMessageInvocationCountError) Error 

func (amie AgentMessageInvocationCountError) Error() string

func (AgentMessageInvocationCountError) Name 

func (amie AgentMessageInvocationCountError) Name() string

func (AgentMessageInvocationCountError) ToIPLD 

func (amie AgentMessageInvocationCountError) ToIPLD() (ipld.Node, error)

type CachingServer 

type CachingServer interface {
	server.Server[Service]
	Cache() delegation.Store
}

CachingServer is a retrieval server that also caches invocations/delegations to allow invocations with delegations chains bigger than HTTP header size limits to be executed as multiple requests.

type HandlerFunc 

type HandlerFunc[C any, O ipld.Builder, X failure.IPLDBuilderFailure] func(
	ctx context.Context,
	capability ucan.Capability[C],
	invocation invocation.Invocation,
	context server.InvocationContext,
	request Request,
) (result result.Result[O, X], fx fx.Effects, resp Response, err error)

HandlerFunc is an invocation handler function. It is different to server.HandlerFunc in that it allows an Response to be returned, which for a retrieval server will determine the HTTP headers and body content of the HTTP response. The usual handler response (out and effects) are added to the X-Agent-Message HTTP header.

type MemoryDelegationCache 

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

func NewMemoryDelegationCache 

func NewMemoryDelegationCache(size int) (*MemoryDelegationCache, error)

NewMemoryDelegationCache creates a new in memory LRU cache for delegations that implements [DelegationStore]. The size parameter controls the maximum number of delegations that can be cached. Pass a value less than 1 to use the default cache size MemoryDelegationCacheSize.

func (*MemoryDelegationCache) Get 

func (m *MemoryDelegationCache) Get(ctx context.Context, root ipld.Link) (delegation.Delegation, bool, error)

func (*MemoryDelegationCache) Put 

func (m *MemoryDelegationCache) Put(ctx context.Context, d delegation.Delegation) error

type MissingProofs 

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

func NewMissingProofsError 

func NewMissingProofsError(proofs []ipld.Link) MissingProofs

func (MissingProofs) Error 

func (mpe MissingProofs) Error() string

func (MissingProofs) Name 

func (mpe MissingProofs) Name() string

func (MissingProofs) Proofs 

func (mpe MissingProofs) Proofs() []ipld.Link

func (MissingProofs) ToIPLD 

func (mpe MissingProofs) ToIPLD() (ipld.Node, error)

type Option 

type Option func(cfg *srvConfig) error

Option is an option configuring a ucanto retrieval server. It does not include a transport codec option as it must be headercar.

func WithAlternativeAudiences 

func WithAlternativeAudiences(audiences ...ucan.Principal) Option

WithAlternativeAudiences configures a set of alternative audiences that will be assumed by the service. Invocations targeted to the service itself or any of the alternative audiences will be accepted.

func WithAuthorityProofs 

func WithAuthorityProofs(proofs ...delegation.Delegation) Option

WithAuthorityProofs allows to provide a list of proofs that designate other principals (beyond the service authority) whose attestations will be recognized as valid.

func WithCanIssue 

func WithCanIssue(fn validator.CanIssueFunc[any]) Option

WithCanIssue configures a function that determines whether a given capability can be issued by a given DID or whether it needs to be delegated to the issuer.

func WithDelegationCache 

func WithDelegationCache(cache delegation.Store) Option

WithDelegationCache configures a delegation cache for the server - if not configured an in-memory cache is used.

func WithErrorHandler 

func WithErrorHandler(fn server.ErrorHandlerFunc) Option

WithErrorHandler configures a function to be called when errors occur during execution of a handler.

func WithPrincipalParser 

func WithPrincipalParser(fn validator.PrincipalParserFunc) Option

WithPrincipalParser configures a function that provides verifier instances that can validate UCANs issued by a given principal.

func WithPrincipalResolver 

func WithPrincipalResolver(fn validator.PrincipalResolverFunc) Option

WithPrincipalResolver configures a function that resolves the key of a principal that is identified by DID different from did:key method.

func WithProofResolver 

func WithProofResolver(fn validator.ProofResolverFunc) Option

WithProofResolver configures a function that finds delegations corresponding to a given link. If a resolver is not provided the validator may not be able to explore corresponding path within a proof chain.

func WithReceiptLogger added in v0.6.3 

func WithReceiptLogger(fn server.ReceiptLoggerFunc) Option

WithReceiptLogger configures a function to be called when a receipt is generated, allowing access to the receipts produced by the server.

func WithRevocationChecker 

func WithRevocationChecker(fn validator.RevocationCheckerFunc[any]) Option

WithRevocationChecker configures the function used to check UCANs for revocation.

func WithServiceMethod 

func WithServiceMethod[O ipld.Builder, X failure.IPLDBuilderFailure](can string, handler ServiceMethod[O, X]) Option

type Request 

type Request struct {
	// Relative URL requested.
	URL *url.URL
	// Headers are the HTTP headers sent in the HTTP request to the server.
	Headers http.Header
}

type Response 

type Response struct {
	// Status is the HTTP status that should be returned. e.g. 206 when returning
	// a range request.
	Status int
	// Headers are additional HTTP headers to return in the response. At minimum
	// they should include the Content-Length header, but should also include
	// Content-Range for byte range responses.
	Headers http.Header
	// Body is the data to return in the response body.
	Body io.ReadCloser
}

func Execute 

func Execute(ctx context.Context, srv CachingServer, msg message.AgentMessage, req Request) (message.AgentMessage, Response, error)

func NewResponse 

func NewResponse(status int, headers http.Header, body io.ReadCloser) Response

func Run 

func Run(ctx context.Context, srv server.Server[Service], invocation server.ServiceInvocation, req Request) (receipt.AnyReceipt, Response, error)

Run is similar to server.Run except the receipts that are issued do not include the invocation block(s) in order to save bytes when transmitting the receipt in HTTP headers.

type Server 

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

func NewServer 

func NewServer(id principal.Signer, options ...Option) (*Server, error)

NewServer creates a retrieval server, which is a UCAN server that comes pre-loaded with a headercar codec.

Handlers have an additional return value - the data to return in the body of the response as well as HTTP headers and status code. They also have an additional parameter, which are the details of the request - the URL that was requested and the HTTP headers.

They require a delegation cache, which allows delegations that are too big for the header to be sent in multiple rounds. By default an in-memory cache is provided if none is passed in options.

The carheader codec will accept agent messages where the invocation is a CID that can be looked up in the delegations cache.

The delegations cache should be a size bounded LRU to prevent DoS attacks.

func (*Server) Cache 

func (srv *Server) Cache() delegation.Store

func (*Server) Catch 

func (srv *Server) Catch(err server.HandlerExecutionError[any])

func (*Server) Codec 

func (srv *Server) Codec() transport.InboundCodec

func (*Server) Context 

func (srv *Server) Context() server.InvocationContext

func (*Server) ID 

func (srv *Server) ID() principal.Signer

func (*Server) LogReceipt added in v0.6.3 

func (srv *Server) LogReceipt(ctx context.Context, rcpt receipt.AnyReceipt, inv invocation.Invocation) error

func (*Server) Request 

func (srv *Server) Request(ctx context.Context, request transport.HTTPRequest) (transport.HTTPResponse, error)

Request handles an inbound HTTP request to the retrieval server. The request URL will only be non-empty if this method is called with a request that is a transport.InboundHTTPRequest.

func (*Server) Run 

func (srv *Server) Run(ctx context.Context, invocation server.ServiceInvocation) (receipt.AnyReceipt, error)

func (*Server) Service 

func (srv *Server) Service() Service

type Service 

type Service = map[ucan.Ability]ServiceMethod[ipld.Builder, failure.IPLDBuilderFailure]

Service is a mapping of service names to handlers, used to define a service implementation.

type ServiceMethod 

type ServiceMethod[O ipld.Builder, X failure.IPLDBuilderFailure] func(
	context.Context,
	invocation.Invocation,
	server.InvocationContext,
	Request,
) (transaction.Transaction[O, X], Response, error)

ServiceMethod is an invocation handler. It is different to server.ServiceMethod in that it allows an Response to be returned as part of the [transation.Transation], which for a retrieval server will determine the HTTP headers and body content of the HTTP response. The usual handler response (out and effects) are added to the X-Agent-Message HTTP header.

func Provide 

func Provide[C any, O ipld.Builder, X failure.IPLDBuilderFailure](
	capability validator.CapabilityParser[C],
	handler HandlerFunc[C, O, X],
) ServiceMethod[O, failure.IPLDBuilderFailure]

Provide is used to define given capability provider. It decorates the passed handler and takes care of UCAN validation. It only calls the handler when validation succeeds.

Source Files

View all Source files

Directories

Path Synopsis

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.