Documentation
¶
Overview ¶
Package api wraps Huma with Soro routing, errors, resources, and middleware.
Index ¶
- Constants
- func HTTPError(ctx context.Context, err error) error
- func Register[I, O any](router *Router, operation huma.Operation, ...) error
- func RequestID(ctx context.Context) string
- func WithAudience(policy AudiencePolicy) func(*huma.Operation)
- type API
- type Action
- type Audience
- type AudienceAuthorizer
- type AudiencePolicy
- type Config
- type ErrorBody
- type ErrorEnvelope
- type Middleware
- type Option
- type PaginationMeta
- type Registrar
- type Resource
- type ResourceConfig
- type ResourceHook
- type Route
- type Router
- type StatusError
Constants ¶
const ( AudienceHeader = "X-Soro-API-Audience" AudienceExtension = "x-soro-audience" AudienceScopesExtension = "x-soro-required-scopes" AudienceClientAudienceExtension = "x-soro-client-audience" )
const RequestIDHeader = "X-Request-ID"
Variables ¶
This section is empty.
Functions ¶
func WithAudience ¶
func WithAudience(policy AudiencePolicy) func(*huma.Operation)
WithAudience marks a Huma operation. Soro validates and enforces the policy when the operation is registered.
Types ¶
type API ¶
type API struct {
// contains filtered or unexported fields
}
type Audience ¶
type Audience string
Audience describes who may build a client for an operation. It is additive to normal authentication, authorization, tenant isolation, and auditing.
type AudienceAuthorizer ¶
type AudienceAuthorizer interface {
RequireScopes(context.Context, Audience, []string) error
AuthenticateClient(context.Context, *http.Request, string) (context.Context, error)
}
AudienceAuthorizer bridges Soro's audience policy to application-owned principal scopes and software-client credentials. AuthenticateClient may return a derived context containing the authenticated client identity.
type AudiencePolicy ¶
AudiencePolicy is the complete audience requirement for one operation. ClientAudience is required only for first-party operations.
func FirstParty ¶
func FirstParty(clientAudience string, requiredScope string, additionalScopes ...string) AudiencePolicy
FirstParty requires both normal scoped principal authorization and an independent software-client credential for clientAudience.
func SecondParty ¶
func SecondParty(requiredScope string, additionalScopes ...string) AudiencePolicy
SecondParty requires one or more elevated scopes granted to vetted clients.
func ThirdParty ¶
func ThirdParty(requiredScopes ...string) AudiencePolicy
ThirdParty describes the public developer surface. An empty scope list is explicit public/anonymous access; otherwise normal scope authorization runs.
func (AudiencePolicy) Validate ¶
func (policy AudiencePolicy) Validate() error
type Config ¶
type Config struct {
Title string
Version string
BasePath string
OpenAPIPath string
DocsPath string
SchemasPath string
MaxBodyBytes int64
}
func DefaultConfig ¶
func DefaultConfig() Config
type ErrorEnvelope ¶
type ErrorEnvelope struct {
Error ErrorBody `json:"error"`
}
type Option ¶
type Option func(*settings)
func WithAudienceAuthorizer ¶
func WithAudienceAuthorizer(authorizer AudienceAuthorizer) Option
func WithLogger ¶
func WithMiddleware ¶
func WithMiddleware(middleware ...Middleware) Option
func WithRequestIDGenerator ¶
type PaginationMeta ¶
type Resource ¶
type Resource[T, C, U, R any] struct { // contains filtered or unexported fields }
Resource implements the five conventional REST operations for one model.
func NewResource ¶
func NewResource[T, C, U, R any](config ResourceConfig[T, C, U, R]) (*Resource[T, C, U, R], error)
type ResourceConfig ¶
type ResourceConfig[T, C, U, R any] struct { Name string Repository *repository.Repository[T] Serializer serializer.Serializer[T, R] CreateEntity func(context.Context, C) (*T, error) UpdateEntity func(context.Context, *T, U) error Query query.Definition Disabled []Action Authorize ResourceHook[T] Before ResourceHook[T] After ResourceHook[T] Scope func(context.Context, *bun.SelectQuery) *bun.SelectQuery Audience AudiencePolicy Audiences map[Action]AudiencePolicy ModifyOperation map[Action]func(*huma.Operation) }
ResourceConfig describes a typed REST resource. CreateEntity and UpdateEntity are deliberately explicit so API input can never be reflectively assigned to a persistence model.
type StatusError ¶
type StatusError struct {
ErrorEnvelope
// contains filtered or unexported fields
}
func (*StatusError) ContentType ¶
func (response *StatusError) ContentType(contentType string) string
func (*StatusError) Error ¶
func (response *StatusError) Error() string
func (*StatusError) GetStatus ¶
func (response *StatusError) GetStatus() int