apis

Documentation

Overview

Package apis implements the default PocketBase api services and middlewares.

Index

• Constants
• func ActivityLogger(app core.App) echo.MiddlewareFunc
• func EnrichRecord(c echo.Context, dao *daos.Dao, record *models.Record, defaultExpands ...string) error
• func EnrichRecords(c echo.Context, dao *daos.Dao, records []*models.Record, ...) error
• func InitApi(app core.App) (*echo.Echo, error)
• func LoadAuthContext(app core.App) echo.MiddlewareFunc
• func LoadCollectionContext(app core.App, optCollectionTypes ...string) echo.MiddlewareFunc
• func RecordAuthResponse(app core.App, c echo.Context, authRecord *models.Record, meta any, ...) error
• func RequestData(c echo.Context) *models.RequestInfo
• func RequestInfo(c echo.Context) *models.RequestInfo
• func RequireAdminAuth() echo.MiddlewareFunc
• func RequireAdminAuthOnlyIfAny(app core.App) echo.MiddlewareFunc
• func RequireAdminOrOwnerAuth(ownerIdParam string) echo.MiddlewareFunc
• func RequireAdminOrRecordAuth(optCollectionNames ...string) echo.MiddlewareFunc
• func RequireGuestOnly() echo.MiddlewareFunc
• func RequireRecordAuth(optCollectionNames ...string) echo.MiddlewareFunc
• func RequireSameContextRecordAuth() echo.MiddlewareFunc
• func Serve(app core.App, config ServeConfig) (*http.Server, error)
• func StaticDirectoryHandler(fileSystem fs.FS, indexFallback bool) echo.HandlerFunc
• type ApiError
  • func NewApiError(status int, message string, data any) *ApiError
  • func NewBadRequestError(message string, data any) *ApiError
  • func NewForbiddenError(message string, data any) *ApiError
  • func NewNotFoundError(message string, data any) *ApiError
  • func NewUnauthorizedError(message string, data any) *ApiError
  • func (e *ApiError) Error() string
  • func (e *ApiError) RawData() any
• type ServeConfig

Constants

const (
	ContextAdminKey      string = "admin"
	ContextAuthRecordKey string = "authRecord"
	ContextCollectionKey string = "collection"
)

Common request context keys used by the middlewares and api handlers.

const ContextRequestInfoKey = "requestInfo"

Functions

func ActivityLogger

func ActivityLogger(app core.App) echo.MiddlewareFunc

ActivityLogger middleware takes care to save the request information into the logs database.

The middleware does nothing if the app logs retention period is zero (aka. app.Settings().Logs.MaxDays = 0).

func EnrichRecord

func EnrichRecord(c echo.Context, dao *daos.Dao, record *models.Record, defaultExpands ...string) error

EnrichRecord parses the request context and enrich the provided record:

• expands relations (if defaultExpands and/or ?expand query param is set)
• ensures that the emails of the auth record and its expanded auth relations are visibe only for the current logged admin, record owner or record with manage access

func EnrichRecords

func EnrichRecords(c echo.Context, dao *daos.Dao, records []*models.Record, defaultExpands ...string) error

EnrichRecords parses the request context and enriches the provided records:

• expands relations (if defaultExpands and/or ?expand query param is set)
• ensures that the emails of the auth records and their expanded auth relations are visibe only for the current logged admin, record owner or record with manage access

func InitApi

func InitApi(app core.App) (*echo.Echo, error)

InitApi creates a configured echo instance with registered system and app specific routes and middlewares.

func LoadAuthContext

func LoadAuthContext(app core.App) echo.MiddlewareFunc

LoadAuthContext middleware reads the Authorization request header and loads the token related record or admin instance into the request's context.

This middleware is expected to be already registered by default for all routes.

func LoadCollectionContext

func LoadCollectionContext(app core.App, optCollectionTypes ...string) echo.MiddlewareFunc

LoadCollectionContext middleware finds the collection with related path identifier and loads it into the request context.

Set optCollectionTypes to further filter the found collection by its type.

func RecordAuthResponse

func RecordAuthResponse(
	app core.App,
	c echo.Context,
	authRecord *models.Record,
	meta any,
	finalizers ...func(token string) error,
) error

RecordAuthResponse writes standardised json record auth response into the specified request context.

func RequestData

func RequestData(c echo.Context) *models.RequestInfo

Deprecated: Use RequestInfo instead.

func RequestInfo

func RequestInfo(c echo.Context) *models.RequestInfo

RequestInfo exports cached common request data fields (query, body, logged auth state, etc.) from the provided context.

func RequireAdminAuth

func RequireAdminAuth() echo.MiddlewareFunc

RequireAdminAuth middleware requires a request to have a valid admin Authorization header.

func RequireAdminAuthOnlyIfAny

func RequireAdminAuthOnlyIfAny(app core.App) echo.MiddlewareFunc

RequireAdminAuthOnlyIfAny middleware requires a request to have a valid admin Authorization header ONLY if the application has at least 1 existing Admin model.

func RequireAdminOrOwnerAuth

func RequireAdminOrOwnerAuth(ownerIdParam string) echo.MiddlewareFunc

RequireAdminOrOwnerAuth middleware requires a request to have a valid admin or auth record owner Authorization header set.

This middleware is similar to [apis.RequireAdminOrRecordAuth()] but for the auth record token expects to have the same id as the path parameter ownerIdParam (default to "id" if empty).

func RequireAdminOrRecordAuth

func RequireAdminOrRecordAuth(optCollectionNames ...string) echo.MiddlewareFunc

RequireAdminOrRecordAuth middleware requires a request to have a valid admin or record Authorization header set.

You can further filter the allowed auth record collections by providing their names.

This middleware is the opposite of [apis.RequireGuestOnly()].

func RequireGuestOnly

func RequireGuestOnly() echo.MiddlewareFunc

RequireGuestOnly middleware requires a request to NOT have a valid Authorization header.

This middleware is the opposite of [apis.RequireAdminOrRecordAuth()].

func RequireRecordAuth

func RequireRecordAuth(optCollectionNames ...string) echo.MiddlewareFunc

RequireRecordAuth middleware requires a request to have a valid record auth Authorization header.

The auth record could be from any collection.

You can further filter the allowed record auth collections by specifying their names.

Example:

apis.RequireRecordAuth()

Or:

apis.RequireRecordAuth("users", "supervisors")

To restrict the auth record only to the loaded context collection, use [apis.RequireSameContextRecordAuth()] instead.

func RequireSameContextRecordAuth

func RequireSameContextRecordAuth() echo.MiddlewareFunc

RequireSameContextRecordAuth middleware requires a request to have a valid record Authorization header.

The auth record must be from the same collection already loaded in the context.

func Serve

func Serve(app core.App, config ServeConfig) (*http.Server, error)

Serve starts a new app web server.

NB! The app should be bootstrapped before starting the web server.

Example:

app.Bootstrap()
apis.Serve(app, apis.ServeConfig{
	HttpAddr:        "127.0.0.1:8080",
	ShowStartBanner: false,
})

func StaticDirectoryHandler

func StaticDirectoryHandler(fileSystem fs.FS, indexFallback bool) echo.HandlerFunc

StaticDirectoryHandler is similar to `echo.StaticDirectoryHandler` but without the directory redirect which conflicts with RemoveTrailingSlash middleware.

If a file resource is missing and indexFallback is set, the request will be forwarded to the base index.html (useful also for SPA).

@see https://github.com/labstack/echo/issues/2211

Types

type ApiError

type ApiError struct {
	Code    int            `json:"code"`
	Message string         `json:"message"`
	Data    map[string]any `json:"data"`
	// contains filtered or unexported fields
}

ApiError defines the struct for a basic api error response.

func NewApiError

func NewApiError(status int, message string, data any) *ApiError

NewApiError creates and returns new normalized `ApiError` instance.

func NewBadRequestError

func NewBadRequestError(message string, data any) *ApiError

NewBadRequestError creates and returns 400 `ApiError`.

func NewForbiddenError

func NewForbiddenError(message string, data any) *ApiError

NewForbiddenError creates and returns 403 `ApiError`.

func NewNotFoundError

func NewNotFoundError(message string, data any) *ApiError

NewNotFoundError creates and returns 404 `ApiError`.

func NewUnauthorizedError

func NewUnauthorizedError(message string, data any) *ApiError

NewUnauthorizedError creates and returns 401 `ApiError`.

func (*ApiError) Error

func (e *ApiError) Error() string

Error makes it compatible with the `error` interface.

func (*ApiError) RawData

func (e *ApiError) RawData() any

RawData returns the unformatted error data (could be an internal error, text, etc.)

type ServeConfig

type ServeConfig struct {
	// ShowStartBanner indicates whether to show or hide the server start console message.
	ShowStartBanner bool

	// HttpAddr is the TCP address to listen for the HTTP server (eg. `127.0.0.1:80`).
	HttpAddr string

	// HttpsAddr is the TCP address to listen for the HTTPS server (eg. `127.0.0.1:443`).
	HttpsAddr string

	// Optional domains list to use when issuing the TLS certificate.
	//
	// If not set, the host from the bound server address will be used.
	//
	// For convenience, for each "non-www" domain a "www" entry and
	// redirect will be automatically added.
	CertificateDomains []string

	// AllowedOrigins is an optional list of CORS origins (default to "*").
	AllowedOrigins []string
}

ServeConfig defines a configuration struct for apis.Serve().