Skip to content

STD-API-034: API Gateway Plugin Standards

Owner Classification Review Date Status
CDO Office Internal April 2027 Active

STD-API-034: API Gateway Plugin Standards

Field Value
Standard STD-API-034
Title API Gateway Plugin Standards
Status Draft
Owner Platform Team
Created 2026-04-03
Review Quarterly

Purpose

Standardise the development, review, testing and deployment of custom KrakenD plugins written in Go. The API gateway processes every request to the platform — a poorly written plugin can introduce latency, security vulnerabilities, or outages. This standard ensures plugins are safe, performant and maintainable.

Scope

All custom plugins loaded into Simpaisa's KrakenD API gateway. This includes request/response modifiers, authentication handlers, rate-limit extensions, logging enrichment, and any other middleware. Off-the-shelf KrakenD features configured via JSON are out of scope.

Plugin Architecture

  • KrakenD supports Go plugins compiled as shared objects (.so files).

  • Plugins must be compiled against the exact same Go version and KrakenD version as the gateway image.

  • Plugins run in-process — a panic in a plugin crashes the gateway. Defensive coding is mandatory.

Naming Convention

  • Repository: simpaisa-plugin-{name} (e.g., simpaisa-plugin-merchant-auth, simpaisa-plugin-rate-limiter).

  • Go module: bitbucket.org/simpaisa/simpaisa-plugin-{name}.

  • Plugin binary: simpaisa-plugin-{name}.so.

  • KrakenD config key: simpaisa/{name} in the extra_config block.

Development Requirements

Code Standards

  • Written in Go, following Simpaisa Go coding standards (GO-SERVICE-TEMPLATE-SPEC.md).

  • No external network calls from plugins — plugins must operate on in-memory request/response data only.

  • No goroutine leaks — all spawned goroutines must have bounded lifetimes.

  • Recover from panics — every plugin entry point must have a defer recover() guard.

  • Structured logging via KrakenD's logger interface, not fmt.Println or log.Println.

  • No use of unsafe package without explicit Security Team approval.

Performance Requirements

  • Latency budget : A plugin must not add more than 5ms to request processing at P99.

  • Memory : No per-request heap allocations exceeding 4KB. Use sync.Pool for buffers.

  • CPU : Plugin benchmarks must demonstrate <1% CPU overhead under load.

  • Benchmarks are run as part of CI using go test -bench with a standardised load profile.

Security Requirements

  • Mandatory security review by the Security Team before first deployment.

  • Plugins handling authentication or authorisation require a threat model (documented in THREAT-MODEL-CARDS.md).

  • No hardcoded secrets — configuration injected via KrakenD environment variables.

  • Input validation on all data read from request headers, query parameters, or body.

  • No logging of PII, tokens, or payment data (enforced by log scrubbing rules).

Testing Requirements

Unit Tests

  • Minimum 80% code coverage.

  • Test all happy paths, error paths, and edge cases (empty headers, malformed input, oversized payloads).

  • Mock KrakenD interfaces using the github.com/krakendio/krakend-ce test utilities.

Integration Tests

  • Run against a KrakenD test harness: a minimal KrakenD instance with the plugin loaded.

  • Test harness is provided as a Docker Compose file in the plugin repository.

  • Integration tests send real HTTP requests through KrakenD and verify plugin behaviour.

  • Must test: plugin load/unload, configuration parsing, request transformation, error handling.

Performance Tests

  • go test -bench results captured in CI and compared against baseline.

  • Any regression >1ms at P99 fails the build.

  • Load test with k6 against the KrakenD test harness: 1000 RPS for 60 seconds, measure added latency.

Deployment

  • Plugins are compiled and bundled into the KrakenD Docker image at build time.

  • The Dockerfile for KrakenD includes a multi-stage build: compile plugins, then copy .so files into the runtime image.

  • Plugin versions are pinned in the KrakenD image build manifest.

  • Rolling updates only — never hot-reload plugins in a running gateway.

  • Canary deployment: new plugin versions deployed to one gateway pod first, observed for 30 minutes before full rollout.

Review and Approval

Stage Reviewer Criteria
Code review 2 senior engineers Code quality, Go idioms, error handling
Security review Security Team Input validation, no secrets, no PII leaks
Performance review Platform Team Benchmark results within budget
Deployment approval Platform Lead All tests pass, canary plan documented

Actions

# Action Owner Deadline
1 Publish KrakenD plugin template repository Platform Team 2026-Q2
2 Create KrakenD test harness Docker Compose Platform Team 2026-Q2
3 Audit existing plugins against this standard Platform Team 2026-Q2
4 Integrate benchmark regression checks into CI Platform Team 2026-Q3

References

  • API-STANDARDS.md

  • GO-SERVICE-TEMPLATE-SPEC.md

  • INFRASTRUCTURE-STANDARDS.md

  • SECURITY-ARCHITECTURE.md