api

Documentation

Overview

Package api defines this project's request-context wrapper around echo.Context and the glue that lets routers declare handlers as `func(c Context) error` instead of `func(c echo.Context) error`.

Why this layer exists:

• One context value satisfies both echo.Context (request/response, binding) and context.Context (deadline/cancellation propagation into services), so handlers can pass `c` straight through.
• Project-wide accessors (credential, session, trace-id) and custom binders live here, so adding one doesn't ripple through every handler signature.

The framework's API server only accepts echo.HandlerFunc / func(echo.Context, *websocket.Conn) error. WrapHandler / WrapWebSocket / DiscoverHandlers bridge our richer signatures back to those at router registration time.

Index

• func DiscoverHandlers(r any) map[string]any
• func WrapHandler(hf HandlerFunc) echo.HandlerFunc
• func WrapWebSocket(wf WebSocketHandlerFunc) func(echo.Context, *websocket.Conn) error
• type CertificateCreateResponse
• type CertificateGenerateRequest
• type CertificateUpdateRequest
• type CertificateUploadRequest
• type Context
• type HandlerFunc
• type HelloWorldCreateRequest
• type LoginRequest
• type LoginResponse
• type UserCreateRequest
• type UserCreateResponse
• type UserResetPasswordRequest
• type UserUpdateRequest
• type WebSocketHandlerFunc

Functions

func DiscoverHandlers

func DiscoverHandlers(r any) map[string]any

DiscoverHandlers reflects over r's methods and returns those matching a known handler signature, keyed by method name. It lets a router expose

func (r *router) Handlers() map[string]any { return api.DiscoverHandlers(r) }

instead of hand-listing every method, and transparently wraps `func(Context) error` / `func(Context, *websocket.Conn) error` methods into the echo-compatible signatures the framework expects. Methods named "Handlers" are skipped so the router's own Handlers() doesn't recurse.

func WrapHandler

func WrapHandler(hf HandlerFunc) echo.HandlerFunc

func WrapWebSocket

func WrapWebSocket(wf WebSocketHandlerFunc) func(echo.Context, *websocket.Conn) error

Types

type CertificateCreateResponse

type CertificateCreateResponse struct {
	CertificateID int32 `json:"certificate_id"`
}

type CertificateGenerateRequest

type CertificateGenerateRequest struct {
	Name           string `json:"name" validate:"required"`
	CommonName     string `json:"common_name" validate:"required"`
	SubjectAltName string `json:"subject_alt_name"`
	CAID           int32  `json:"ca_id" validate:"required"`
}

type CertificateUpdateRequest

type CertificateUpdateRequest struct {
	Comments string `json:"comments"`
}

type CertificateUploadRequest

type CertificateUploadRequest struct {
	Type     string `json:"type" form:"type" validate:"required"`
	IsCA     bool   `json:"is_ca" form:"is_ca"`
	Name     string `json:"name" form:"name" validate:"required"`
	Password string `json:"password" form:"password"`
}

type Context

type Context interface {
	// echo wrap: echo.Context for request/response handling,
	// context.Context for cancellation/deadline propagation, plus
	// thin helpers over Echo's parameter binders.
	echo.Context
	context.Context
	BindQuery() *echo.ValueBinder
	BindPath() *echo.ValueBinder
	BindForm() *echo.ValueBinder
	BindAny(i any) error

	// helpers: typed accessors for values stashed into the echo
	// context by middleware (auth, tracing). They return (_, false)
	// when the value is missing or the wrong type, so handlers don't
	// have to repeat the assertion dance.
	Credential() (*entity.Credential, bool)
	Session() (*entity.Session, bool)
	TraceID() (string, bool)
}

Context is the per-request value passed to router handlers. It embeds echo.Context (so handlers keep all of Echo's API) and context.Context (so handlers can hand `c` to any context-aware service call without unwrapping to c.Request().Context() first).

type HandlerFunc

type HandlerFunc func(Context) error

type HelloWorldCreateRequest

type HelloWorldCreateRequest struct {
	Message string `json:"message" form:"message" query:"message" validate:"required"`
}

type LoginRequest

type LoginRequest struct {
	Username string `json:"username" form:"username" validate:"required"`
	Password string `json:"password" form:"password" validate:"required"`
}

type LoginResponse

type LoginResponse struct {
	RequirePasswordReset bool `json:"require_password_reset"`
}

type UserCreateRequest

type UserCreateRequest struct {
	Username       string `json:"username" validate:"required"`
	Password       string `json:"password" validate:"required"`
	Title          string `json:"title"`
	FirstName      string `json:"first_name"`
	LastName       string `json:"last_name"`
	Email          string `json:"email"`
	Role           string `json:"role" validate:"required"`
	ChangePassword bool   `json:"change_password"`
}

type UserCreateResponse

type UserCreateResponse struct {
	UserID int32 `json:"user_id"`
}

type UserResetPasswordRequest

type UserResetPasswordRequest struct {
	Password    string `json:"password" validate:"required"`
	OldPassword string `json:"old_password"`
}

type UserUpdateRequest

type UserUpdateRequest struct {
	Username       *string `json:"username,omitempty"`
	Title          *string `json:"title,omitempty"`
	FirstName      *string `json:"first_name,omitempty"`
	LastName       *string `json:"last_name,omitempty"`
	Email          *string `json:"email,omitempty"`
	Role           *string `json:"role,omitempty"`
	ChangePassword bool    `json:"change_password"`
}

type WebSocketHandlerFunc

type WebSocketHandlerFunc func(Context, *websocket.Conn) error