Plugin API

The Plugin interface allows extending API Gateway functionality.

Interface Definition

type Plugin interface {
    Prepare(app *zoox.Application, cfg *config.Config) error
    OnRequest(ctx *zoox.Context, req *http.Request) error
    OnResponse(ctx *zoox.Context, res *http.Response) error
}

Methods

Prepare

Prepare(app *zoox.Application, cfg *config.Config) error

Called during gateway initialization. Use this to:

• Register middleware
• Set up routes
• Initialize resources

Parameters:

• app (*zoox.Application): The Zoox application instance
• cfg (*config.Config): Gateway configuration

Returns:

• error: Error if initialization fails

OnRequest

OnRequest(ctx *zoox.Context, req *http.Request) error

Called before forwarding the request to the backend. Use this to:

• Modify request headers
• Transform request body
• Add authentication
• Log requests

Parameters:

• ctx (*zoox.Context): Request context
• req (*http.Request): HTTP request (can be modified)

Returns:

• error: Error to stop processing and return error response

OnResponse

OnResponse(ctx *zoox.Context, res *http.Response) error

Called after receiving the response from the backend. Use this to:

• Modify response headers
• Transform response body
• Add caching headers
• Log responses

Parameters:

• ctx (*zoox.Context): Request context
• res (*http.Response): HTTP response (can be modified)

Returns:

• error: Error to return error response

Example Implementation

package myplugin

import (
    "net/http"
    "github.com/go-zoox/api-gateway/config"
    "github.com/go-zoox/api-gateway/plugin"
    "github.com/go-zoox/zoox"
)

type MyPlugin struct {
    plugin.Plugin
    // Plugin configuration
}

func (p *MyPlugin) Prepare(app *zoox.Application, cfg *config.Config) error {
    // Initialize plugin
    app.Use(func(ctx *zoox.Context) {
        // Middleware logic
        ctx.Next()
    })
    return nil
}

func (p *MyPlugin) OnRequest(ctx *zoox.Context, req *http.Request) error {
    // Modify request
    req.Header.Set("X-Custom-Header", "value")
    return nil
}

func (p *MyPlugin) OnResponse(ctx *zoox.Context, res *http.Response) error {
    // Modify response
    res.Header.Set("X-Response-Header", "value")
    return nil
}

Registering Plugins

Plugins are registered programmatically:

app, err := core.New(version, cfg)
if err != nil {
    // handle error
}

app.Plugin(&myplugin.MyPlugin{
    // configuration
})

err = app.Run()

Built-in Plugins

BaseURI Plugin

The BaseURI plugin is automatically enabled when baseuri is configured:

type BaseURI struct {
    plugin.Plugin
    BaseURI string
}

This plugin filters requests by base URI prefix.

JSON audit plugin

The JSON audit plugin is registered when global json_audit.enable is true or any route enables json_audit.enable:

// github.com/go-zoox/api-gateway/plugin/jsonaudit
type JSONAudit struct {
    plugin.Plugin
}

The json_audit keys map to config.JSONAudit (same shape as route.JSONAudit). Prepare loads the global block from cfg.JSONAudit and per-route overrides from cfg.Routes[*].JSONAudit; for each request, the effective settings use the longest matching route prefix, falling back to the global block when it is enabled.

It logs paired request/response bodies when the upstream response is JSON-like. See the JSON audit plugin guide.

IP policy plugin

The IP policy plugin is registered when global ip_policy.enable is true or any route enables ip_policy.enable:

// github.com/go-zoox/api-gateway/plugin/ippolicy
type IPPolicy struct { plugin.Plugin }

It registers HTTP middleware (before the reverse proxy) to enforce CIDR allow/deny lists. OnRequest / OnResponse are no-ops. See the IP policy guide.

CORS plugin

The CORS plugin is registered when global cors.enable is true or any route enables cors.enable:

// github.com/go-zoox/api-gateway/plugin/cors
type Plugin struct { plugin.Plugin }

It answers OPTIONS preflight in middleware and decorates normal responses in OnResponse. See the CORS guide.

Best Practices

1. Error Handling: Return errors to stop processing
2. Performance: Keep plugin logic lightweight
3. Thread Safety: Ensure plugins are thread-safe
4. Logging: Use context logger for consistent logging
5. Configuration: Access gateway config through cfg parameter

See Also

• Plugins Guide - Plugin overview and built-in plugins
• Config API - Configuration API