Built-in Plugins
No plugin can be enabled through configuration today. The repository does contain plugin
crates — some fully implemented — but nothing registers them with the gateway, and the plugins:
array only loads plugin_type: script entries (see the overview). Entries with
plugin_type: static or dynamic are skipped with a warning.
Treat everything on this page as source to read and build on, not as features you can switch on.
What ships in plugins/01
Seven crates live under the repository's plugins/ directory. They fall into three groups.
Implemented, targeting octopus-plugins
| Crate | Registers as | What it does |
|---|---|---|
auth-jwt | jwt-auth (PluginType::Static) | Complete JWT authentication: token extraction, HS256/RS256 validation, scope checks, and configurable skip-paths. Implements both the octopus-plugins Plugin trait and octopus_core::Middleware. An optional dashboard feature adds a Leptos/WASM admin panel (gated to wasm32). |
This is a workspace member, so it builds and is type-checked in CI. Two things still stop it from
being usable: nothing constructs or registers JwtAuthPlugin at startup, and the crate is a plain
rlib — it emits no cdylib, so the dynamic loader cannot pick it up either.
If you want JWT authentication in production today, use the JWT provider in octopus-auth
instead. It is wired into the request path through the auth gateway middleware. See
Security.
Implemented reference examples, targeting octopus-plugin-api
| Crate | Capability traits | What it demonstrates |
|---|---|---|
example-auth | RequestInterceptor | JWT validation with a configurable secret, skip-routes, and custom error responses. |
example-logging | RequestInterceptor + ResponseInterceptor | Structured request/response logging, selective field logging, and timing metrics. |
example-transform | TransformPlugin | Header add/remove/rename, regex path rewriting, query-parameter manipulation, and conditional rules. |
These are the best starting point for authoring your own plugin — they target the richer
octopus-plugin-api SDK that Writing a Plugin documents.
The three example-* crates are not workspace members. cargo build --workspace and CI never
compile them, so they can drift out of sync with the SDK. Build one directly
(cargo build -p example-auth --manifest-path plugins/example-auth/Cargo.toml) before relying on it.
Stubs — name only, no implementation
| Crate | State |
|---|---|
rate-limiter | Single-line placeholder: // Plugin stub - implementation will be added later |
cache-redis | Same placeholder |
kafka-producer | Same placeholder |
All three are crate-type = ["cdylib"] workspace members, so they compile — into empty shared
libraries. Their names appear in older examples and screenshots; there is no behaviour behind them.
The admin UI's plugin page currently renders a hardcoded demo list containing auth-jwt and
rate-limiter marked as enabled. That is fixture data in octopus-admin, not a live registry
readout — it does not reflect any plugin actually running in your gateway.
What the SDK crates contain02
None of the three SDK/runtime crates ship a concrete Plugin implementation beyond test fixtures.
| Crate | Concrete plugins | What's there instead |
|---|---|---|
octopus-plugin-api | None | The Plugin trait and capability traits (RequestInterceptor, ResponseInterceptor, AuthProvider, TransformPlugin, ProtocolHandler, ScriptInterceptorPlugin), context, and error types. |
octopus-plugin-runtime | None | Lifecycle management (PluginRegistry, PluginManager) and the HotReloadWatcher. |
octopus-plugins | None | The dynamic shared-library PluginLoader and the octopus_declare_plugin! ABI macro. |
The traits, lifecycle, and loader are real and tested. What is missing is the registration wiring that would let a configured plugin name resolve to an implementation.
Where these capabilities live today03
The features you might expect as "built-in plugins" are implemented elsewhere in the gateway as first-class middleware and auth providers — and those are wired into the request path.
Middleware
The octopus-middleware crate provides cross-cutting request/response behaviour as middleware
(not plugins), including request ID, timeout, logging, rate limiting, CORS, compression, IP
filtering, forward auth, caching, header/body transforms, circuit breaking, retry, redirects,
security headers, WAF, bot detection, canary, deduplication, connection/request limits, and audit
logging.
These are configured and applied directly, independent of the plugin system.
Authentication and authorization
Authentication is provided by octopus-auth through its own AuthProvider trait (distinct from the
plugin-api AuthProvider), with built-in providers for JWT, OIDC, API key, forward-auth, and mTLS.
Authorization uses a Rhai-based rule engine and/or OPA. These are wired in via the auth gateway
middleware.
So if you were looking for "JWT authentication" or "rate limiting": they exist and work — just as
middleware / auth providers, configured through their own sections, not as plugins in the
plugins: array.
Roadmap04
Two pieces of work stand between the crates above and a usable built-in plugin set: filling in the
three stubs, and adding the registry that maps a plugins: entry to a registered implementation.
The two SDK layers (octopus-plugins and octopus-plugin-api) also need to converge — auth-jwt
targets one, the example-* crates the other. When that lands, this page will document each shipped
plugin's configuration keys.