server

Documentation

Index

• func Execute(server Server, msg message.AgentMessage) (message.AgentMessage, error)
• func Handle(server Server, request transport.HTTPRequest) (transport.HTTPResponse, error)
• func ParsePrincipal(str string) (principal.Verifier, error)
• func Run(server Server, invocation ServiceInvocation) (receipt.AnyReceipt, error)
• type ErrorHandlerFunc
• type HandlerExecutionError
  • func NewHandlerExecutionError[Caveats any](cause error, capability ucan.Capability[Caveats]) HandlerExecutionError[Caveats]
• type HandlerFunc
• type HandlerNotFoundError
  • func NewHandlerNotFoundError[Caveats any](capability ucan.Capability[Caveats]) HandlerNotFoundError[Caveats]
• type InvocationCapabilityError
  • func NewInvocationCapabilityError(capabilities []ucan.Capability[any]) InvocationCapabilityError
• type InvocationContext
• type Option
  • func WithCanIssue(fn validator.CanIssueFunc[any]) Option
  • func WithErrorHandler(fn ErrorHandlerFunc) Option
  • func WithInboundCodec(codec transport.InboundCodec) Option
  • func WithPrincipalParser(fn validator.PrincipalParserFunc) Option
  • func WithPrincipalResolver(fn validator.PrincipalResolverFunc) Option
  • func WithProofResolver(fn validator.ProofResolverFunc) Option
  • func WithRevocationChecker(fn validator.RevocationCheckerFunc[any]) Option
  • func WithServiceMethod[O ipld.Builder](can string, handleFunc ServiceMethod[O]) Option
• type Server
• type ServerView
  • func NewServer(id principal.Signer, options ...Option) (ServerView, error)
• type Service
• type ServiceInvocation
• type ServiceMethod
  • func Provide[C any, O ipld.Builder](capability validator.CapabilityParser[C], handler HandlerFunc[C, O]) ServiceMethod[O]

Functions

func Execute

func Execute(server Server, msg message.AgentMessage) (message.AgentMessage, error)

func Handle

func Handle(server Server, request transport.HTTPRequest) (transport.HTTPResponse, error)

func ParsePrincipal

func ParsePrincipal(str string) (principal.Verifier, error)

func Run

func Run(server Server, invocation ServiceInvocation) (receipt.AnyReceipt, error)

Types

type ErrorHandlerFunc

type ErrorHandlerFunc func(err HandlerExecutionError[any])

ErrorHandlerFunc allows non-result errors generated during handler execution to be logged.

type HandlerExecutionError

type HandlerExecutionError[Caveats any] interface {
	failure.Failure
	failure.WithStackTrace
	Cause() error
	Capability() ucan.Capability[Caveats]
}

func NewHandlerExecutionError

func NewHandlerExecutionError[Caveats any](cause error, capability ucan.Capability[Caveats]) HandlerExecutionError[Caveats]

type HandlerFunc

type HandlerFunc[C any, O ipld.Builder] func(capability ucan.Capability[C], invocation invocation.Invocation, context InvocationContext) (out O, fx fx.Effects, err error)

type HandlerNotFoundError

type HandlerNotFoundError[Caveats any] interface {
	failure.Failure
	Capability() ucan.Capability[Caveats]
}

func NewHandlerNotFoundError

func NewHandlerNotFoundError[Caveats any](capability ucan.Capability[Caveats]) HandlerNotFoundError[Caveats]

type InvocationCapabilityError

type InvocationCapabilityError interface {
	failure.Failure
	Capabilities() []ucan.Capability[any]
}

func NewInvocationCapabilityError

func NewInvocationCapabilityError(capabilities []ucan.Capability[any]) InvocationCapabilityError

type InvocationContext

type InvocationContext interface {
	validator.RevocationChecker[any]
	validator.CanIssuer[any]
	validator.ProofResolver
	validator.PrincipalParser
	validator.PrincipalResolver
	// ID is the DID of the service the invocation was sent to.
	ID() principal.Signer
}

InvocationContext is the context provided to service methods.

type Option

type Option func(cfg *srvConfig) error

Option is an option configuring a ucanto server.

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 WithErrorHandler

func WithErrorHandler(fn ErrorHandlerFunc) Option

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

func WithInboundCodec

func WithInboundCodec(codec transport.InboundCodec) Option

WithInboundCodec configures the codec used to decode requests and encode responses.

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 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](can string, handleFunc ServiceMethod[O]) Option

type Server

type Server interface {
	// ID is the DID which will be used to verify that received invocation
	// audience matches it.
	ID() principal.Signer
	Codec() transport.InboundCodec
	Context() InvocationContext
	// Service is the actual service providing capability handlers.
	Service() Service
	Catch(err HandlerExecutionError[any])
}

type ServerView

type ServerView interface {
	Server
	transport.Channel
	// Run executes a single invocation and returns a receipt.
	Run(invocation ServiceInvocation) (receipt.AnyReceipt, error)
}

Server is a materialized service that is configured to use a specific transport channel. It has a invocation context which contains the DID of the service itself, among other things.

func NewServer

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

type Service

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

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

type ServiceInvocation

type ServiceInvocation = invocation.IssuedInvocation

type ServiceMethod

type ServiceMethod[O ipld.Builder] func(input invocation.Invocation, context InvocationContext) (transaction.Transaction[O, ipld.Builder], error)

ServiceMethod is an invocation handler.

func Provide

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

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.