apis

Documentation

Index

• type Api
  • func NewApi(name string, opts ...ApiOption) Api
• type ApiDetails
• type ApiOption
  • func WithMiddleware(middleware Middleware) ApiOption
  • func WithPath(path string) ApiOption
  • func WithSecurity(oidcOptions OidcOptions) ApiOption
  • func WithSecurityJwtRule(name string, rule JwtSecurityRule) ApiOption
• type Ctx
  • func NewCtx(msg *apispb.ServerMessage) *Ctx
  • func (c *Ctx) ToClientMessage() *apispb.ClientMessage
  • func (c *Ctx) WithError(err error)
• type Handler
• type HttpRequest
  • func (h *HttpRequest) Data() []byte
  • func (h *HttpRequest) Headers() textproto.MIMEHeader
  • func (h *HttpRequest) Method() string
  • func (h *HttpRequest) Path() string
  • func (h *HttpRequest) PathParams() map[string]string
  • func (h *HttpRequest) Query() map[string][]string
• type JwtSecurityRule
• type MethodOption
  • func WithMethodSecurity(oidcOptions OidcOptions) MethodOption
  • func WithNoMethodSecurity() MethodOption
• type Middleware
• type OidcOptions
• type OidcSecurityDefinition
• type Request
• type Response
• type Route
• type RouteOption
• type SecurityOption
  • func OidcRule(name string, issuer string, audiences []string) SecurityOption

Types

type Api

type Api interface {
	// Get adds a Get method handler to the path with any specified opts.
	// Valid function signatures:
	//
	//	func()
	//	func() error
	//	func(*apis.Ctx)
	//	func(*apis.Ctx) error
	//	Handler[apis.Ctx]
	Get(path string, handler interface{}, opts ...MethodOption)
	// Put adds a Put method handler to the path with any specified opts.
	// Valid function signatures:
	//
	//	func()
	//	func() error
	//	func(*apis.Ctx)
	//	func(*apis.Ctx) error
	//	Handler[apis.Ctx]
	Put(path string, handler interface{}, opts ...MethodOption)
	// Patch adds a Patch method handler to the path with any specified opts.
	// Valid function signatures:
	//
	//	func()
	//	func() error
	//	func(*apis.Ctx)
	//	func(*apis.Ctx) error
	//	Handler[apis.Ctx]
	Patch(path string, handler interface{}, opts ...MethodOption)
	// Post adds a Post method handler to the path with any specified opts.
	// Valid function signatures:
	//
	//	func()
	//	func() error
	//	func(*apis.Ctx)
	//	func(*apis.Ctx) error
	//	Handler[apis.Ctx]
	Post(path string, handler interface{}, opts ...MethodOption)
	// Delete adds a Delete method handler to the path with any specified opts.
	// Valid function signatures:
	//
	//	func()
	//	func() error
	//	func(*apis.Ctx)
	//	func(*apis.Ctx) error
	//	Handler[apis.Ctx]
	Delete(path string, handler interface{}, opts ...MethodOption)
	// Options adds a Options method handler to the path with any specified opts.
	// Valid function signatures:
	//
	//	func()
	//	func() error
	//	func(*apis.Ctx)
	//	func(*apis.Ctx) error
	//	Handler[apis.Ctx]
	Options(path string, handler interface{}, opts ...MethodOption)
	// NewRoute creates a new Route object for the given path.
	NewRoute(path string, opts ...RouteOption) Route
}

Api Resource represents an HTTP API, capable of routing and securing incoming HTTP requests to handlers. path is the route path matcher e.g. '/home'. Supports path params via colon prefix e.g. '/customers/:customerId' handler the handler to register for callbacks.

func NewApi

func NewApi(name string, opts ...ApiOption) Api

NewApi Registers a new API Resource.

The returned API object can be used to register Routes and Methods, with Handlers.

type ApiDetails

type ApiDetails struct {
	resources.Details
	URL string
}

type ApiOption

type ApiOption func(api *api)

func WithMiddleware

func WithMiddleware(middleware Middleware) ApiOption

WithMiddleware - Apply a middleware function to all handlers in the API

func WithPath

func WithPath(path string) ApiOption

WithPath - Set the base path for the API

func WithSecurity

func WithSecurity(oidcOptions OidcOptions) ApiOption

WithSecurity - Apply security settings to the API

func WithSecurityJwtRule

func WithSecurityJwtRule(name string, rule JwtSecurityRule) ApiOption

WithSecurityJwtRule - Apply a JWT security rule to the API

type Ctx

type Ctx struct {
	Request  Request
	Response *Response
	Extras   map[string]interface{}
	// contains filtered or unexported fields
}

func NewCtx

func NewCtx(msg *apispb.ServerMessage) *Ctx

func (*Ctx) ToClientMessage

func (c *Ctx) ToClientMessage() *apispb.ClientMessage

func (*Ctx) WithError

func (c *Ctx) WithError(err error)

type Handler

type Handler = handlers.Handler[Ctx]

type HttpRequest

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

func (*HttpRequest) Data

func (h *HttpRequest) Data() []byte

func (*HttpRequest) Headers

func (h *HttpRequest) Headers() textproto.MIMEHeader

func (*HttpRequest) Method

func (h *HttpRequest) Method() string

func (*HttpRequest) Path

func (h *HttpRequest) Path() string

func (*HttpRequest) PathParams

func (h *HttpRequest) PathParams() map[string]string

func (*HttpRequest) Query

func (h *HttpRequest) Query() map[string][]string

type JwtSecurityRule

type JwtSecurityRule struct {
	Issuer    string
	Audiences []string
}

type MethodOption

type MethodOption func(mo *methodOptions)

func WithMethodSecurity

func WithMethodSecurity(oidcOptions OidcOptions) MethodOption

WithMethodSecurity - Override/set the security settings for a method

func WithNoMethodSecurity

func WithNoMethodSecurity() MethodOption

WithNoMethodSecurity - Disable security for a method

type Middleware

type Middleware = handlers.Middleware[Ctx]

type OidcOptions

type OidcOptions struct {
	Name      string
	Issuer    string
	Audiences []string
	Scopes    []string
}

type OidcSecurityDefinition

type OidcSecurityDefinition interface{}

type Request

type Request interface {
	Method() string
	Path() string
	Data() []byte
	Query() map[string][]string
	Headers() textproto.MIMEHeader
	PathParams() map[string]string
}

type Response

type Response struct {
	Status  int
	Headers map[string][]string
	Body    []byte
}

type Route

type Route interface {
	// All adds a handler for all HTTP methods to the route.
	All(handler interface{}, opts ...MethodOption)
	// Get adds a Get method handler to the route.
	Get(handler interface{}, opts ...MethodOption)
	// Put adds a Put method handler to the route.
	Patch(handler interface{}, opts ...MethodOption)
	// Patch adds a Patch method handler to the route.
	Put(handler interface{}, opts ...MethodOption)
	// Post adds a Post method handler to the route.
	Post(handler interface{}, opts ...MethodOption)
	// Delete adds a Delete method handler to the route.
	Delete(handler interface{}, opts ...MethodOption)
	// Options adds an Options method handler to the route.
	Options(handler interface{}, opts ...MethodOption)
	// ApiName returns the name of the API this route belongs to.
	ApiName() string
}

Route providers convenience functions to register a handler in a single method.

type RouteOption

type RouteOption func(route Route)

type SecurityOption

type SecurityOption = func(scopes []string) OidcOptions

func OidcRule

func OidcRule(name string, issuer string, audiences []string) SecurityOption