Marketplace developer guide

:::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.

:::

What maps to current implementation

The current release-bundled step path is the versioned StepService: Describe, Configure, ProcessRequest, ProcessResponse, Health, and OnConnectionClose. Describe publishes phases, contract version, document-access profile, config schema, command filters, and concurrency hints. Non-built-in steps with missing or incompatible phase/version data fail closed.

A separate repository-local WASM experiment defines Init, request/response, route, connect/disconnect, and shutdown hooks. It is not a public SDK or deployed marketplace contract. The retired Rust macros, AssemblyScript support, HTTP capability, shared cache, typed BSON helpers, and plugin developer account are not present as supported public surfaces.

Retired architecture and lifecycle concepts

The retired model described WASM modules receiving MongoDB messages in request, response, router, and connection phases. It claimed filesystem/network/process isolation, plugin-scoped state, metrics, logs, optional HTTP/KV capabilities, CPU/memory/response-size limits, and generated configuration forms. Treat all of that as design intent unless independently confirmed by a current release contract.

Manifest fields — historical YAML shape

The YAML example covers identity (name, version, author, license, description, homepage), phases, min_nexo_version, tier, category, draft-07 config_schema, and resources (max_memory_mb, max_cpu_ms_per_request, max_response_size_bytes). The repository currently contains three different shapes: this YAML story, nexoctl's loose manifest.json, and first-party step.yaml. They are not interchangeable.

Hooks

Legacy hook	Legacy meaning	Current qualification
on_request	Inspect/modify before MongoDB	Closest current RPC: ProcessRequest
on_response	Inspect/modify before client	Closest current RPC: ProcessResponse
on_route	Select upstream	Current contract carries RoutingDecision on RequestResult; no public marketplace hook guarantee
on_connect	Accept/reject connection	Repository-local WASM API only
on_disconnect	Cleanup	Closest current RPC: OnConnectionClose
init	Load configuration	Closest current RPC: Configure
shutdown	Graceful cleanup	Repository-local lifecycle detail, not protobuf RPC

Repository-local WASM manifest shape

The local plugin.Manifest implementation reads JSON or YAML with these fields. This is implementation evidence, not a public artifact schema.

Area	Fields and local validation
Identity	name, version, author (string), description, license, homepage; name/version required
Phases	request, response, router, connection; at least one required
Compatibility	min_nexo_version; stored but not a public marketplace compatibility promise
Resources	max_memory_mb (default 64, maximum 256), max_cpu_ms_per_request (default 10, maximum 100), max_response_size_bytes (the manifest helper conditionally assigns 1 MiB only when applying the entire default resource bundle; no runtime enforcement was found)
Permissions	outbound network host strings and storage max_keys/max_value_bytes; declaration does not establish a supported egress policy
Configuration	inline draft-07 config_schema; no public dashboard-rendering guarantee
Marketplace metadata	price_monthly_usd, free_trial_days, category, tags; descriptive only

The generated nexoctl manifest is a separate loose shape:

{
  "name": "example-plugin",
  "version": "0.1.0",
  "description": "A Nexo pipeline plugin",
  "author": "",
  "license": "Apache-2.0",
  "type": "both",
  "language": "go",
  "pricing": {"model": "free"},
  "entrypoint": "example-plugin.so",
  "sdk_version": ">=0.1.0",
  "tags": [],
  "homepage": "",
  "repository": ""
}

validate does not enforce most of those fields; publish additionally requires author and pricing.

Current nexoctl development workflow and limitations

1. nexoctl scaffold --name NAME --type request|response|both --lang go|wasm writes main.go, go.mod, manifest.json, README, and Makefile. Both language choices currently receive the same Go plugin template and .so build, so the WASM scaffold is incomplete.
2. nexoctl validate --dir DIR checks only basic JSON fields, a three-part version, optional type, an internal Azure DevOps SDK string in go.mod, and a Go build. It is not marketplace compliance, JSON Schema, sandbox-import, signature, asset, or resource validation.
3. nexoctl test --plugin-path FILE requires an existing artifact, rebuilds its directory as a Go plugin, and attempts a fixed localhost:27017 smoke test. “SKIP (no proxy available)” still ends as complete and is not pass evidence.
4. nexoctl publish --dry-run --dir DIR creates a tarball. It recursively includes files except hidden directories, vendor, and node_modules; hidden files are included. Inspect a clean staging directory. Non-dry-run exposes the API key in argv and targets an unsupported endpoint.

Security and sandboxing qualification

The local wazero code sets a linear-memory page cap and creates timeout contexts around hook calls, plus host functions for logging, counters, histograms, and plugin-scoped KV. The runtime configuration does not enable cancellation-driven termination, so a non-returning untrusted WASM invocation is not proven enforceable by those timeout contexts. It instantiates WASI for clock/random. The legacy claims about HTTP allowlists, no network, pass-through on CPU timeout, repeated-violation delisting, signed licenses, offline JWT enforcement, and automatic marketplace review are not current contracts.

Plugins inspect database traffic and may see credentials, PII, or full BSON. Minimize data_access_profile, avoid body logging, reject rather than silently bypass security failures, bound state, validate lengths before parsing wire bytes, and never treat an illustrative sandbox as a substitute for admission, provenance, and deployment controls.

Related pages

• Step contract reference — authoritative protobuf/gRPC contract definition.
• Plugin SDK and contract reference — current contract families, actions, opcodes, and WASM interface.
• nexoctl commands — scaffold, validate, test, and publish reference with known limitations.
• Examples — repository-local TinyGo rate limiter and design pattern descriptions.
• Publishing and policy — manifest fields, versioning, and current limitations.
• Support — how to report issues.