jsendx

Documentation

Overview

Package jsendx implements an extended JSend response envelope for HTTP APIs.

Problem

API handlers often return heterogeneous payload shapes, making client code harder to implement and operational debugging harder to automate. Teams usually need one predictable JSON envelope for both success and error responses, plus application metadata useful for traceability.

Solution

This package wraps all payloads in a consistent Response schema that extends JSend with runtime metadata:

• program name, version, and release
• RFC3339 datetime and Unix-nanosecond timestamp
• HTTP code/message and JSend status projection
• arbitrary response data payload

The JSXResp helper integrates with github.com/tecnickcom/nurago/pkg/httputil to send wrapped JSON responses and includes ready-to-use default handlers for common service endpoints and router fallbacks.

Features

• Uniform response envelope for 2xx/4xx/5xx outputs.
• Automatic metadata enrichment through AppInfo.
• Prebuilt handler factories for not-found, method-not-allowed, panic, index, ping, status, and public-IP endpoints.
• Direct adapter for healthcheck result writing via JSXResp.HealthCheckResultWriter.
• Compatibility with nurago HTTP server abstractions (httpserver.IndexHandlerFunc, healthcheck.ResultWriter).

Benefits

jsendx standardizes API response contracts across handlers, reduces repetitive response formatting code, and improves observability/debuggability for both humans and API clients.

Index

• type AppInfo
• type JSXResp
  • func NewJSXResp(h *httputil.HTTPResp) *JSXResp
  • func (jr *JSXResp) DefaultIPHandler(info *AppInfo, fn httpserver.GetPublicIPFunc) http.HandlerFunc
  • func (jr *JSXResp) DefaultIndexHandler(info *AppInfo) httpserver.IndexHandlerFunc
  • func (jr *JSXResp) DefaultMethodNotAllowedHandlerFunc(info *AppInfo) http.HandlerFunc
  • func (jr *JSXResp) DefaultNotFoundHandlerFunc(info *AppInfo) http.HandlerFunc
  • func (jr *JSXResp) DefaultPanicHandlerFunc(info *AppInfo) http.HandlerFunc
  • func (jr *JSXResp) DefaultPingHandler(info *AppInfo) http.HandlerFunc
  • func (jr *JSXResp) DefaultStatusHandler(info *AppInfo) http.HandlerFunc
  • func (jr *JSXResp) HealthCheckResultWriter(info *AppInfo) healthcheck.ResultWriter
  • func (jr *JSXResp) Send(ctx context.Context, w http.ResponseWriter, statusCode int, info *AppInfo, ...)
• type Response
  • func Wrap(statusCode int, info *AppInfo, data any) *Response

Examples

• Wrap

Types

type AppInfo

type AppInfo struct {
	// ProgramName is the application name.
	ProgramName string
	// ProgramVersion is the application semantic version.
	ProgramVersion string
	// ProgramRelease is the application build/release identifier.
	ProgramRelease string
}

AppInfo contains application metadata used to enrich JSendX responses.

type JSXResp

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

JSXResp holds the configuration for the HTTP response methods.

func NewJSXResp

func NewJSXResp(h *httputil.HTTPResp) *JSXResp

NewJSXResp returns a new JSXResp instance.

A nil h falls back to a default httputil.HTTPResp (which logs to slog.Default()).

func (*JSXResp) DefaultIPHandler

func (jr *JSXResp) DefaultIPHandler(info *AppInfo, fn httpserver.GetPublicIPFunc) http.HandlerFunc

DefaultIPHandler returns a handler that resolves and returns the public IP in JSendX format.

func (*JSXResp) DefaultIndexHandler

func (jr *JSXResp) DefaultIndexHandler(info *AppInfo) httpserver.IndexHandlerFunc

DefaultIndexHandler returns an index handler that renders routes in JSendX format.

func (*JSXResp) DefaultMethodNotAllowedHandlerFunc

func (jr *JSXResp) DefaultMethodNotAllowedHandlerFunc(info *AppInfo) http.HandlerFunc

DefaultMethodNotAllowedHandlerFunc returns the default handler used when a route exists but the method is not allowed.

func (*JSXResp) DefaultNotFoundHandlerFunc

func (jr *JSXResp) DefaultNotFoundHandlerFunc(info *AppInfo) http.HandlerFunc

DefaultNotFoundHandlerFunc returns the default handler used when no route matches.

func (*JSXResp) DefaultPanicHandlerFunc

func (jr *JSXResp) DefaultPanicHandlerFunc(info *AppInfo) http.HandlerFunc

DefaultPanicHandlerFunc returns the default handler for recovered panics.

func (*JSXResp) DefaultPingHandler

func (jr *JSXResp) DefaultPingHandler(info *AppInfo) http.HandlerFunc

DefaultPingHandler returns a ping handler that responds in JSendX format.

func (*JSXResp) DefaultStatusHandler

func (jr *JSXResp) DefaultStatusHandler(info *AppInfo) http.HandlerFunc

DefaultStatusHandler returns a status handler that responds in JSendX format.

func (*JSXResp) HealthCheckResultWriter

func (jr *JSXResp) HealthCheckResultWriter(info *AppInfo) healthcheck.ResultWriter

HealthCheckResultWriter returns a healthcheck.ResultWriter that emits JSendX responses.

func (*JSXResp) Send

func (jr *JSXResp) Send(ctx context.Context, w http.ResponseWriter, statusCode int, info *AppInfo, data any)

Send writes a JSON response wrapped in the JSendX envelope.

The data payload must be JSON-marshalable; if marshaling fails, the response falls back to a plain-text 500 Internal Server Error rather than a JSendX envelope (see httputil.HTTPResp.SendJSON).

type Response

type Response struct {
	// Program is the application name.
	Program string `json:"program"`

	// Version is the program semantic version (e.g. 1.2.3).
	Version string `json:"version"`

	// Release is the program build number that is appended to the version.
	Release string `json:"release"`

	// DateTime is the human-readable date and time when the response is sent.
	DateTime string `json:"datetime"`

	// Timestamp is the machine-readable UTC timestamp in nanoseconds since EPOCH.
	Timestamp int64 `json:"timestamp"`

	// Status code string (i.e.: error, fail, success).
	Status httputil.Status `json:"status"`

	// Code is the HTTP status code number.
	Code int `json:"code"`

	// Message is the error or general HTTP status message.
	Message string `json:"message"`

	// Data is the content payload.
	Data any `json:"data"`
}

Response wraps payload data in a JSend-compatible response envelope.

func Wrap

func Wrap(statusCode int, info *AppInfo, data any) *Response

Wrap builds a Response for statusCode using info metadata and data payload.

A nil info is treated as an empty AppInfo so the response is still produced (with empty program metadata) instead of panicking.

Example

package main

import (
	"fmt"
	"net/http"

	"github.com/tecnickcom/nurago/pkg/httputil/jsendx"
)

func main() {
	info := &jsendx.AppInfo{
		ProgramName:    "demo",
		ProgramVersion: "1.0.0",
		ProgramRelease: "1",
	}

	resp := jsendx.Wrap(http.StatusOK, info, "payload")

	// Only the deterministic fields are printed; DateTime and Timestamp vary per call.
	fmt.Println(resp.Program, resp.Version, resp.Release, resp.Code, resp.Message, resp.Data)

}

Output:
demo 1.0.0 1 200 OK payload