Documentation
¶
Index ¶
- Constants
- func Body[T any](c *gin.Context) (T, error)
- func GetBoolQuery(c *gin.Context, key string) (bool, error)
- func GetInt32Param(c *gin.Context, key string) (int32, error)
- func GetInt32Query(c *gin.Context, key string) (int32, error)
- func GetInt64Param(c *gin.Context, key string) (int64, error)
- func GetInt64Query(c *gin.Context, key string) (int64, error)
- func GetParam(c *gin.Context, key string) (string, error)
- func GetQuery(c *gin.Context, key string) (*string, error)
- func GetTenantID(c *gin.Context) (uuid.UUID, error)
- func GetTenantUserID(c *gin.Context) (uuid.UUID, uuid.UUID, error)
- func GetUUIDParam(c *gin.Context, key string) (uuid.UUID, error)
- func GetUUIDQuery(c *gin.Context, key string) (uuid.UUID, error)
- func GetUserID(c *gin.Context) (uuid.UUID, error)
- func LoggerFrom(ctx context.Context) *slog.Logger
- func MergeParams(r *http.Request) map[string]string
- func PagedRequest(c *gin.Context) *types.PagedResultRequest
- func RequestID(c *gin.Context) string
- func WriteAutoPostForm(w http.ResponseWriter, action string, fields map[string]string) error
- type Client
- func (c *Client) Do(ctx context.Context, method, path string, body, out any, opts ...RequestOption) error
- func (c *Client) GetJSON(ctx context.Context, path string, out any, opts ...RequestOption) error
- func (c *Client) PostJSON(ctx context.Context, path string, body, out any, opts ...RequestOption) error
- type ClientOption
- func WithDefaultHeader(key, value string) ClientOption
- func WithHTTPClient(h *http.Client) ClientOption
- func WithRetry(maxRetries int, baseBackoff time.Duration) ClientOption
- func WithRetryableMethods(methods ...string) ClientOption
- func WithRetryableStatuses(statuses ...int) ClientOption
- func WithTimeout(d time.Duration) ClientOption
- type QueryParamBase
- type ReadinessFunc
- type RequestOption
- type Server
- func (s *Server) AddReadinessCheck(name string, fn ReadinessFunc)
- func (s *Server) Addr() string
- func (s *Server) Close() error
- func (s *Server) ErrCh() <-chan error
- func (s *Server) Init() error
- func (s *Server) ReadConfig(l core.ConfigReader) error
- func (s *Server) Start() error
- func (s *Server) Stop(ctx context.Context) error
- type ServerConfig
Constants ¶
const DefaultClientTimeout = 30 * time.Second
DefaultClientTimeout bounds every request made by a Client that was not given its own *http.Client, so a hung upstream cannot block a caller forever.
const DefaultMaxBackoff = 30 * time.Second
DefaultMaxBackoff caps the per-attempt retry wait.
Variables ¶
This section is empty.
Functions ¶
func Body ¶
Body decodes and validates the JSON request body into a value of type T. It returns the value directly (not a pointer): request bodies are value-shaped data, and returning T avoids a nil-pointer footgun on the error path.
func GetTenantUserID ¶ added in v0.11.0
func GetUUIDParam ¶ added in v0.11.0
func GetUUIDQuery ¶ added in v0.11.0
func LoggerFrom ¶
LoggerFrom returns the request-scoped logger carried by ctx (tagged with the request id), falling back to slog.Default() when none is present.
func MergeParams ¶
MergeParams collects request parameters from both the URL query string and the POST form body into a single map, so a handler can read them uniformly whether the caller used GET or POST. When a key appears in both, the POST form value wins. It is handy for callbacks where the sender's method is not under your control (e.g. payment-gateway return URLs).
func PagedRequest ¶
func PagedRequest(c *gin.Context) *types.PagedResultRequest
PagedRequest builds a pagination request from the query string. The pageSize query param defaults to 10 when absent, and a malformed pageSize also falls back to 10 rather than erroring — listing endpoints favor a sensible default over rejecting the request.
func RequestID ¶
RequestID returns the correlation id for the current request (set by the RequestID middleware), or "" if none.
func WriteAutoPostForm ¶
WriteAutoPostForm writes a self-submitting HTML form that POSTs fields to action and submits itself on load (with a no-script fallback button). Use it to bounce a browser to an upstream that requires a POST with hidden fields — for example a payment page that expects form-posted credentials. The action and all field names/values are HTML-escaped.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a small JSON-over-HTTP client for calling external services (payment gateways, partner APIs, internal microservices). It marshals request bodies to JSON, decodes JSON responses into a caller-supplied value, and turns non-2xx responses into structured *core.Error values. Construct one per upstream with NewClient and reuse it; it is safe for concurrent use.
func NewClient ¶
func NewClient(baseURL string, opts ...ClientOption) *Client
NewClient creates a Client. baseURL may be empty, in which case request paths must be absolute URLs.
func (*Client) Do ¶
func (c *Client) Do(ctx context.Context, method, path string, body, out any, opts ...RequestOption) error
Do performs a request with an optional JSON body and decodes a JSON response. It returns a *core.Error (Internal) for transport failures and non-2xx responses; the response body is attached to the error's Params for diagnosis. When retries are enabled (WithRetry) it transparently re-attempts retryable failures, returning the last error if all attempts fail.
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures a Client at construction time.
func WithDefaultHeader ¶
func WithDefaultHeader(key, value string) ClientOption
WithDefaultHeader adds a header sent on every request (e.g. an API key).
func WithHTTPClient ¶
func WithHTTPClient(h *http.Client) ClientOption
WithHTTPClient sets the underlying *http.Client (for custom timeouts, proxies, or transport-level instrumentation).
func WithRetry ¶
func WithRetry(maxRetries int, baseBackoff time.Duration) ClientOption
WithRetry enables automatic retries: up to maxRetries extra attempts on transport errors and retryable status codes, using exponential backoff with jitter starting at baseBackoff. Only idempotent methods are retried by default (GET, HEAD, PUT, DELETE, OPTIONS); customize with WithRetryableMethods and WithRetryableStatuses. Retries always honor the request context.
func WithRetryableMethods ¶
func WithRetryableMethods(methods ...string) ClientOption
WithRetryableMethods overrides which HTTP methods are eligible for retry.
func WithRetryableStatuses ¶
func WithRetryableStatuses(statuses ...int) ClientOption
WithRetryableStatuses overrides which response status codes trigger a retry.
func WithTimeout ¶
func WithTimeout(d time.Duration) ClientOption
WithTimeout sets the request timeout on the default client. Ignored if WithHTTPClient supplied a client.
type QueryParamBase ¶
type QueryParamBase struct {
// contains filtered or unexported fields
}
func (*QueryParamBase) BindQueryParams ¶
func (q *QueryParamBase) BindQueryParams(c *gin.Context, target any) error
BindQueryParams maps query parameters onto the tagged fields of target (a pointer to a struct) and records them in the param map. A malformed value (e.g. ?id=notauuid) returns a core.BadRequest error naming the offending parameter rather than silently substituting a zero value.
func (*QueryParamBase) GetMap ¶
func (q *QueryParamBase) GetMap() map[string]any
func (*QueryParamBase) SetField ¶
func (q *QueryParamBase) SetField(name string, value any)
type ReadinessFunc ¶
ReadinessFunc reports whether a dependency is ready to serve traffic. It should return nil when healthy and an error describing the problem otherwise.
type RequestOption ¶
RequestOption customises a single request (e.g. a per-call bearer token).
func WithHeader ¶
func WithHeader(key, value string) RequestOption
WithHeader sets a header on one request, overriding any default of the same key.
type Server ¶
func NewServer ¶
func NewServer(cfg ServerConfig, logger *slog.Logger) *Server
NewServer creates the router with its middleware stack and standard routes (/health, /metrics, /readyz, and /swagger if debug). The server does not start listening until Init is called.
func (*Server) AddReadinessCheck ¶
func (s *Server) AddReadinessCheck(name string, fn ReadinessFunc)
AddReadinessCheck registers a named dependency probe consulted by GET /readyz. Safe for concurrent use.
func (*Server) Addr ¶
Addr returns the listener address. Before Init it is derived from the config; after Init it reflects the bound address.
func (*Server) Close ¶ added in v0.4.0
Close implements core.Closer, gracefully draining and stopping the server.
func (*Server) ErrCh ¶ added in v0.4.0
ErrCh returns the channel that receives the server's exit error (or nil on clean shutdown via Stop). The host reads this to react to unexpected failures.
func (*Server) Init ¶ added in v0.4.0
Init implements core.Initer. It builds the underlying http.Server but does not begin listening, leaving a window for setup work (route registration) before the server serves. Call Start (the host does this in its start phase) to serve.
func (*Server) ReadConfig ¶ added in v0.11.0
func (s *Server) ReadConfig(l core.ConfigReader) error
ReadConfig implements core.Configurable, reading the [server] section so the server owns its configuration independently of host.Config.
Source Files
Directories