Envelope - 💧 Mizu

Overview

The envelope middleware wraps all responses in a consistent structure, adding metadata like status, pagination, and timestamps. Use it when you need:

Consistent API responses
Response metadata
Standardized error format

Installation

import "github.com/go-mizu/mizu/middlewares/envelope"

Quick Start

app := mizu.New()

app.Use(envelope.New())

app.Get("/users", func(c *mizu.Ctx) error {
    return c.JSON(200, users)
})
// Response: {"success": true, "data": [...users]}

Configuration

Options

Option	Type	Default	Description
`SuccessKey`	`string`	`"success"`	Success field name
`DataKey`	`string`	`"data"`	Data field name
`ErrorKey`	`string`	`"error"`	Error field name
`IncludeTimestamp`	`bool`	`false`	Add timestamp
`IncludeRequestID`	`bool`	`false`	Add request ID

Examples

Default Envelope

app.Use(envelope.New())
// Success: {"success": true, "data": {...}}
// Error: {"success": false, "error": "message"}

With Metadata

app.Use(envelope.WithOptions(envelope.Options{
    IncludeTimestamp: true,
    IncludeRequestID: true,
}))
// {"success": true, "data": {...}, "timestamp": "...", "request_id": "..."}

Custom Structure

app.Use(envelope.WithOptions(envelope.Options{
    SuccessKey: "ok",
    DataKey:    "result",
    ErrorKey:   "message",
}))
// {"ok": true, "result": {...}}

With Pagination

app.Use(envelope.New())

app.Get("/users", func(c *mizu.Ctx) error {
    envelope.SetMeta(c, map[string]any{
        "page":       1,
        "per_page":   20,
        "total":      100,
        "total_pages": 5,
    })
    return c.JSON(200, users)
})
// {"success": true, "data": [...], "meta": {"page": 1, ...}}

API Reference

Functions

// New creates envelope middleware
func New() mizu.Middleware

// WithOptions creates with configuration
func WithOptions(opts Options) mizu.Middleware

// SetMeta adds metadata to response
func SetMeta(c *mizu.Ctx, meta map[string]any)

Response Format

Success Response

{
    "success": true,
    "data": { ... },
    "meta": { ... }
}

Error Response

{
    "success": false,
    "error": "Error message",
    "code": "ERROR_CODE"
}

Technical Details

Implementation Architecture

The envelope middleware uses a custom response writer (envelopeWriter) to intercept and capture the original response before wrapping it in the envelope structure.

Response Writer

The middleware captures responses through a buffer-based writer:

Intercepts WriteHeader() calls to capture HTTP status codes
Buffers response body through Write() calls
Stores status code (defaults to 200 if not explicitly set)

Envelope Construction

The envelope is constructed after the handler completes:

Content-Type Check: Only wraps responses matching configured content types (default: application/json)
Success Determination: Status codes 200-399 are considered successful
Response Parsing: Original JSON response is unmarshaled into the data field
Error Handling: For error responses, attempts to extract error message from:
- error field in response body
- message field in response body
- Handler error if available
Metadata Addition: When IncludeMeta is enabled, adds status code and request ID
Re-encoding: Final envelope is marshaled to JSON and written to the original writer

Field Customization

All field names are customizable through options:

SuccessField: Controls the success indicator field name
DataField: Controls the data payload field name
ErrorField: Controls the error message field name

Content-Type Filtering

The middleware only wraps responses with matching content types:

Checks exact match or with charset suffix (e.g., application/json; charset=utf-8)
Non-matching responses pass through unmodified
Default content types: ["application/json"]

Helper Functions

The package provides convenience functions for common responses:

Success(): 200 OK with data
Created(): 201 Created with data
NoContent(): 204 No Content
BadRequest(): 400 Bad Request with error message
Unauthorized(): 401 Unauthorized with error message
Forbidden(): 403 Forbidden with error message
NotFound(): 404 Not Found with error message
InternalError(): 500 Internal Server Error with error message

Best Practices

Use consistent structure across APIs
Include relevant metadata
Document envelope format
Handle nested errors properly

Testing

The envelope middleware includes comprehensive tests covering all functionality:

Test Case	Description	Expected Behavior
`TestNew`	Default middleware initialization	Wraps response with `success: true` and `data` field
`TestWithOptions_IncludeMeta`	Metadata inclusion with request ID	Includes `meta` object with `status_code` and `request_id`
`TestWithOptions_CustomFields`	Custom field names	Uses custom `ok`, `result`, and `message` fields
`TestSuccess`	Success helper function	Returns 200 OK with `success: true` and data
`TestError`	Error helper function	Returns error status with `success: false` and error message
`TestCreated`	Created helper function	Returns 201 Created status with success response
`TestBadRequest`	BadRequest helper function	Returns 400 Bad Request with error message
`TestUnauthorized`	Unauthorized helper function	Returns 401 Unauthorized with error message
`TestForbidden`	Forbidden helper function	Returns 403 Forbidden with error message
`TestNotFound`	NotFound helper function	Returns 404 Not Found with error message
`TestInternalError`	InternalError helper function	Returns 500 Internal Server Error with error message
`TestNoContent`	NoContent helper function	Returns 204 No Content without body

transformer - Response transformation
requestid - Request IDs
errorpage - Error pages

​Overview

​Installation

​Quick Start

​Configuration

​Options

​Examples

​Default Envelope

​With Metadata

​Custom Structure

​With Pagination

​API Reference

​Functions

​Response Format

​Success Response

​Error Response

​Technical Details

​Implementation Architecture

​Response Writer

​Envelope Construction

​Field Customization

​Content-Type Filtering

​Helper Functions

​Best Practices

​Testing

​Related Middlewares