server

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: 29 Imported by: 15

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Execute 

func Execute(ctx context.Context, server Server[Service], msg message.AgentMessage) (message.AgentMessage, error)

func Handle 

func Handle(ctx context.Context, server Server[Service], request transport.HTTPRequest) (transport.HTTPResponse, error)

func ParsePrincipal 

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

func Run 

func Run(ctx context.Context, server Server[Service], 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, X failure.IPLDBuilderFailure] func(
	ctx context.Context,
	capability ucan.Capability[C],
	invocation invocation.Invocation,
	context InvocationContext,
) (result result.Result[O, X], 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 InvalidAudienceError added in v0.3.0 

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

func NewInvalidAudienceError added in v0.3.0 

func NewInvalidAudienceError(actual ucan.Principal, expected ...ucan.Principal) InvalidAudienceError

func (InvalidAudienceError) Error added in v0.3.0 

func (i InvalidAudienceError) Error() string

func (InvalidAudienceError) Name added in v0.3.0 

func (i InvalidAudienceError) Name() string

func (InvalidAudienceError) ToIPLD added in v0.3.0 

func (i InvalidAudienceError) ToIPLD() (ipld.Node, error)

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
	validator.TimeBoundsValidator
	validator.AuthorityProver
	// ID is the DID of the service the invocation was sent to.
	ID() principal.Signer

	// AlternativeAudiences are other audiences the service will accept for invocations.
	AlternativeAudiences() []ucan.Principal
}

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 WithAlternativeAudiences added in v0.3.1 

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 added in v0.3.0 

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 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 WithReceiptLogger added in v0.6.3 

func WithReceiptLogger(fn ReceiptLoggerFunc) Option

WithReceiptLogger configures a function to be called when a receipt is issued.

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

func WithTimeBoundsValidator added in v0.7.0 

func WithTimeBoundsValidator(fn validator.TimeBoundsValidatorFunc) Option

WithTimeBoundsValidator configures a function that validates the time bounds of a delegation.

type ReceiptLoggerFunc added in v0.6.3 

type ReceiptLoggerFunc func(ctx context.Context, rcpt receipt.AnyReceipt, inv invocation.Invocation) error

ReceiptLoggerFunc allows receipts generated during handler execution to be logged. The original invocation is also provided for reference. Returning an error from this function will cause the server to fail the request and send an error response back to the client, use judiciously.

type Server 

type Server[S any] 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() S
	Catch(err HandlerExecutionError[any])
	LogReceipt(ctx context.Context, rcpt receipt.AnyReceipt, inv invocation.Invocation) error
}

type ServerView 

type ServerView[S any] interface {
	Server[S]
	transport.Channel
	// Run executes a single invocation and returns a receipt.
	Run(ctx context.Context, 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[Service], error)

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 ServiceInvocation 

type ServiceInvocation = invocation.IssuedInvocation

type ServiceMethod 

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

ServiceMethod is an invocation handler.

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
datamodel

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.