api

package
v0.0.0-...-d364ca2 Latest Latest
Warning

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

Go to latest
Published: Aug 17, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package api wraps Huma with Soro routing, errors, resources, and middleware.

Index

Constants

View Source
const (
	AudienceHeader                  = "X-Soro-API-Audience"
	AudienceExtension               = "x-soro-audience"
	AudienceScopesExtension         = "x-soro-required-scopes"
	AudienceClientAudienceExtension = "x-soro-client-audience"
)
View Source
const RequestIDHeader = "X-Request-ID"

Variables

This section is empty.

Functions

func HTTPError

func HTTPError(ctx context.Context, err error) error

func Register

func Register[I, O any](router *Router, operation huma.Operation, handler func(context.Context, *I) (*O, error)) error

func RequestID

func RequestID(ctx context.Context) string

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
}

func New

func New(config Config, options ...Option) (*API, error)

func (*API) Config

func (api *API) Config() Config

func (*API) Handler

func (api *API) Handler() http.Handler

Handler returns the complete HTTP middleware chain.

func (*API) Huma

func (api *API) Huma() huma.API

func (*API) Mux

func (api *API) Mux() *http.ServeMux

func (*API) OpenAPI

func (api *API) OpenAPI() *huma.OpenAPI

func (*API) Routes

func (api *API) Routes() []Route

func (*API) Version

func (api *API) Version(name string, configure func(*Router)) error

type Action

type Action string

Action identifies one of the standard resource operations.

const (
	Index   Action = "index"
	Show    Action = "show"
	Create  Action = "create"
	Update  Action = "update"
	Destroy Action = "destroy"
)

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.

const (
	AudienceFirstParty  Audience = "first_party"
	AudienceSecondParty Audience = "second_party"
	AudienceThirdParty  Audience = "third_party"
)

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

type AudiencePolicy struct {
	Audience       Audience
	RequiredScopes []string
	ClientAudience string
}

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

func (Config) Validate

func (config Config) Validate() error

type ErrorBody

type ErrorBody struct {
	Code      string              `json:"code"`
	Message   string              `json:"message"`
	RequestID string              `json:"request_id,omitempty"`
	Fields    map[string][]string `json:"fields,omitempty"`
}

type ErrorEnvelope

type ErrorEnvelope struct {
	Error ErrorBody `json:"error"`
}

type Middleware

type Middleware func(http.Handler) http.Handler

type Option

type Option func(*settings)

func WithAudienceAuthorizer

func WithAudienceAuthorizer(authorizer AudienceAuthorizer) Option

func WithLogger

func WithLogger(logger *slog.Logger) Option

func WithMiddleware

func WithMiddleware(middleware ...Middleware) Option

func WithRequestIDGenerator

func WithRequestIDGenerator(generator func() string) Option

type PaginationMeta

type PaginationMeta struct {
	Page    int `json:"page"`
	PerPage int `json:"per_page"`
	Total   int `json:"total"`
	Pages   int `json:"pages"`
}

type Registrar

type Registrar interface {
	Register(*Router, string) error
}

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)

func (*Resource[T, C, U, R]) Register

func (resource *Resource[T, C, U, R]) Register(router *Router, path string) 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 ResourceHook

type ResourceHook[T any] func(context.Context, Action, *T) error

type Route

type Route struct {
	Method         string
	Path           string
	OperationID    string
	Tags           []string
	Audience       Audience
	RequiredScopes []string
	ClientAudience string
}

type Router

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

func (*Router) Huma

func (router *Router) Huma() huma.API

func (*Router) Prefix

func (router *Router) Prefix() string

func (*Router) Resource

func (router *Router) Resource(path string, resource Registrar) error

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL