Plugin SDK and contract reference
:::danger Marketplace availability
Nexo does not currently offer a supported public marketplace, public plugin SDK/package or language guarantee, live publishing service, commercial program, review SLA, analytics/ranking service, or marketplace legal terms. Material labeled Legacy/illustrative preserves the retired dashboard documentation for parity; it is not a product promise, API contract, price, policy, or legal agreement.
:::
Contract families: do not mix them
| Family | Identity | Status |
|---|---|---|
| Current step contract | nexo.step.v1.StepService protobuf/gRPC | Implementation-backed for release-bundled steps |
| Current first-party step host | nexo-proxy/pkg/stepsdk | Internal Go bridge; not a public package guarantee |
| Repository-local WASM API | nexo-cli/sdk/go/nexo + nexo-proxy/pkg/plugin | Experimental implementation evidence; no public distribution/compatibility guarantee |
| Retired dashboard SDK | github.com/nexo-proxy/plugin-sdk-go@v1.4.0, Rust macros, imaginary host ABI | Legacy/illustrative and unavailable |
Current protobuf step contract
StepService exposes Describe, Configure, ProcessRequest, ProcessResponse, Health, and OnConnectionClose. RequestMessage and ResponseMessage carry request identity, database, collection, command, decoded BSON bytes, metadata, timing, client/connection data, wire framing, and currently unproduced capability/principal fields. Results carry an explicit action, optional modified BSON, structured error, metadata, principal update, request consumption, routing, and response framing.
Current actions
| Action | Meaning |
|---|---|
ACTION_UNSPECIFIED | Fail-closed zero value; consumers reject it |
FORWARD | Continue with the supplied document |
FORWARD_MODIFIED | Continue with modified document |
REJECT | Return structured ErrorInfo; request results may also mark an internally consumed no-reply request |
SHORT_CIRCUIT | Return a response without forwarding upstream |
Capabilities and phases
StepCapabilities includes backward-compatible processes_responses, command_filter, needs_full_doc, max_concurrency, draft-2020-12 config_schema, authoritative phases, contract_version, and data_access_profile. Phases are request, response, and connection. The router decision is a typed request result, not a separate phase.
Current wire framing and opcodes
WireFraming.op_code records the inbound MongoDB wire opcode; zero means unset and is treated as OP_MSG. The legacy pages list OP_REPLY=1, OP_QUERY=2004, OP_GET_MORE=2005, OP_COMPRESSED=2012, and OP_MSG=2013, plus examples of update/insert/delete. These numeric MongoDB values are useful protocol context, but legacy helper types and parsing packages are not public Nexo APIs.
Repository-local WASM interface
The direct local Go SDK defines NexoPlugin with Init, OnRequest, OnResponse, OnRoute, OnConnect, OnDisconnect, and Shutdown; BasePlugin supplies pass-through defaults. Contexts expose connection ID, client address, command, database, collection, raw messages, setters for modified messages/errors, and logging. RouteContext returns target strings; ConnectContext has connection ID/address.
Its actions are Continue=0, Drop=1, Reject=2, and ShortCircuit=3. This differs from the current protobuf action numbering and semantics. Never pass values between the contracts by numeric cast.
Actual local exports are nexo_init, nexo_on_request, nexo_on_response, nexo_on_route, nexo_on_connect, nexo_on_disconnect, nexo_shutdown, nexo_last_error, and nexo_alloc. Actual imports use module nexo_host: log, metric_counter, metric_histogram, kv_get, kv_set, and kv_delete. The retired nexo_process_*, packed i64 return, module nexo, config/connection/metadata host functions, and SDK v1.4.0 are a different illustrative ABI.
Configuration, errors, logs, testing, and performance
- Current step configuration is opaque bytes plus a version; published schemas are draft 2020-12. Legacy draft-07 schemas, dashboard default injection,
x-nexo-secret, AES-256-GCM claims, secret interpolation, and atomic hot reload are not guaranteed. - Current contract errors use
ErrorInfo(code,message,codename). Legacy reserved Nexo codes 16500–16504 andon_panicbehavior are illustrative. - Local WASM logging/metrics/KV functions exist in code, but metric names, persistence, quotas, and operational support are not public contracts.
- The retired
sdktestbuilders, benchmark harness, zero-copy native SDK, allocation targets, and public examples repository are unavailable guarantees. The general advice—validate bounds, avoid full BSON parsing when metadata suffices, reuse allocations safely, cache bounded decisions, benchmark hot paths—remains sound.
Related pages
- Step contract reference — authoritative protobuf/gRPC contract definition.
- nexoctl commands —
scaffold,validate,test, andpublishcommand reference. - Developer guide — lifecycle, manifests, hooks, workflow, and security.
- Examples — repository-local TinyGo rate limiter and design pattern descriptions.
- Publishing and policy — manifest fields, versioning, and current limitations.
- Pricing — tier capabilities.
- Support — how to report issues.