Documentation
¶
Overview ¶
Package api is Tether's REST layer: an admin API for tenants, devices, roles, live clients, retained messages and stats, and a public HTTP publish endpoint for devices.
Register mounts both on Forge routers. The caller owns authentication of the admin group: Register adds no admin auth of its own.
Index ¶
Constants ¶
const ( // DefaultPageSize is how many tenants or devices a list returns when the // request gives no limit. DefaultPageSize = 100 // MaxPageSize caps the limit a list request may ask for. MaxPageSize = 500 // MaxPublishPayload is the largest decoded payload POST /v1/publish takes // when Services.MaxPublishPayload is zero: the broker's default // MaxPacketSize. A larger one is 413. MaxPublishPayload = 1 << 20 )
Variables ¶
This section is empty.
Functions ¶
func Register ¶
Register mounts the admin routes on admin and POST /v1/publish on public, all relative to those routers' base path. It does not authenticate the admin group: add your own auth middleware to admin with admin.Use first. The routes go on groups nested in admin, which inherit both admin.Use and forge.WithGroupMiddleware since forge v1.13.0 (older forge dropped the second, so prefer Use if you build against one). The publish route authenticates itself with HTTP Basic (key ID and raw key).
It returns an error when a required service is missing or a route cannot be registered; routes registered before the failure stay mounted.
Types ¶
type Services ¶
type Services struct {
Tenants *service.Tenants
Devices *service.Devices
Roles *perm.Roles
Broker *broker.Broker
// Auth, Perms and Limits serve POST /v1/publish: the same authenticator,
// grant loader and rate limiter the broker runs MQTT connections through.
Auth auth.Authenticator
Perms broker.PermLoader
Limits *limits.Limiter
// Entitlement is the broker's entitlement check (broker.Deps.Entitlement),
// asked once per POST /v1/publish after the rate limit and before the
// grants, so a tenant that may not connect may not publish over HTTP
// either. Nil checks nothing.
Entitlement broker.Entitlement
// Logger receives the internal errors the API hides from clients. Nil
// discards them.
Logger *slog.Logger
// MaxPublishPayload is the largest decoded payload POST /v1/publish
// takes, in bytes. Zero (or less) means the MaxPublishPayload constant.
// Set it to the broker's MaxPacketSize so HTTP and MQTT agree.
MaxPublishPayload int
// Audit hears about every admin change once it ran, with its outcome
// and the caller. The dashboard contract emits through the same field.
// Nil records nothing.
Audit audit.Emitter
}
Services are what the handlers call. Everything but Logger is required.
Source Files