API Reference

Complete reference for protoc-gen-nats-micro proto extension options.

Service Options

Service-level configuration using option (natsmicro.service).

Option	Type	Default	Description
subject_prefix	string	Snake-case of service name	NATS subject prefix for all endpoints
name	string	Service name	Service name for NATS micro registration
version	string	"1.0.0"	Service version
description	string	—	Human-readable description
timeout	Duration	No timeout	Default timeout for all endpoints
use_json	bool	false	Use JSON encoding instead of binary protobuf
skip	bool	false	Skip NATS code generation for this service
error_codes	repeated string	—	Custom application-specific error codes

service ProductService {
  option (natsmicro.service) = {
    subject_prefix: "api.v1"
    name: "product_service"
    version: "2.0.0"
    description: "Product catalog API"
    timeout: {seconds: 30}
    error_codes: ["OUT_OF_STOCK", "PRICE_CHANGED"]
  };
}

Endpoint Options

Per-method configuration using option (natsmicro.endpoint).

Option	Type	Default	Description
timeout	Duration	Service timeout	Override timeout for this method
skip	bool	false	Skip NATS generation for this method
metadata	repeated Map	—	Endpoint metadata for discovery

rpc CreateProduct(CreateReq) returns (CreateResp) {
  option (natsmicro.endpoint) = {
    timeout: {seconds: 10}
    metadata: { key: "category" value: "write" }
    metadata: { key: "requires_auth" value: "true" }
  };
}

// Skip this endpoint entirely
rpc AdminReset(ResetReq) returns (ResetResp) {
  option (natsmicro.endpoint).skip = true;
}

KV Store Options

Per-method auto-persistence to NATS KV Store using option (natsmicro.kv_store).

Option	Type	Default	Description
bucket	string	Required	KV bucket name
key_template	string	Required	Key template with {field} placeholders
description	string	—	Bucket description
max_history	int32	—	Max revisions per key
ttl	Duration	—	Time-to-live for entries

rpc SaveProfile(SaveReq) returns (ProfileResp) {
  option (natsmicro.kv_store) = {
    bucket: "user_profiles"
    key_template: "user.{id}"
    max_history: 5
    ttl: {seconds: 3600}
  };
}

Object Store Options

Per-method auto-persistence to NATS Object Store using option (natsmicro.object_store).

Option	Type	Default	Description
bucket	string	Required	Object store bucket name
key_template	string	Required	Key template with {field} placeholders
description	string	—	Bucket description

rpc GenerateReport(ReportReq) returns (ReportResp) {
  option (natsmicro.object_store) = {
    bucket: "reports"
    key_template: "report.{id}"
  };
}

Chunked I/O Options

Per-method helper generation for simple blob transfer over streaming RPC using option (natsmicro.chunked_io).

Option	Type	Default	Description
chunk_field	string	"data"	Name of the bytes field carrying each streamed chunk
default_chunk_size	int32	65536	Default helper chunk size in bytes

Constraints:

• Download helpers (server-streaming) are available for Go, TypeScript, and Python.
• Upload helpers (client-streaming) are currently Go-only.
• Valid only on server-streaming and client-streaming methods.
• The streamed message must contain exactly one bytes field matching chunk_field.
• Metadata belongs in the unary request or final unary response, not in chunk messages.

message SnapshotChunk {
  bytes data = 1;
}

rpc ExportSnapshot(ExportSnapshotRequest) returns (stream SnapshotChunk) {
  option (natsmicro.chunked_io) = {};
}

rpc ImportSnapshot(stream SnapshotChunk) returns (ImportSnapshotResponse) {
  option (natsmicro.chunked_io) = {
    default_chunk_size: 131072
  };
}

Key Template Syntax

Key templates extract values from the request message to build storage keys:

Template	Request Fields	Result
user.{id}	id: "abc"	user.abc
{region}.{id}	region: "us", id: "123"	us.123
orders.{customer_id}.{order_id}	customer_id: "c1", order_id: "o5"	orders.c1.o5

Static segments are kept as-is. {field} placeholders are replaced with the corresponding request field value.

Runtime Options

Server Registration Options

Option	Description
WithName(name)	Override service name
WithVersion(version)	Override version
WithDescription(desc)	Override description
WithSubjectPrefix(prefix)	Override subject prefix
WithTimeout(duration)	Override default timeout
WithMetadata(map)	Replace service metadata
WithAdditionalMetadata(map)	Merge into service metadata
WithServerInterceptor(fn)	Add server-side interceptor
WithJetStream(js)	Enable KV/Object Store auto-create
WithStatsHandler(fn)	Set stats handler
WithDoneHandler(fn)	Set done handler
WithErrorHandler(fn)	Set error handler

Client Options

Option	Description
WithClientSubjectPrefix(prefix)	Override subject prefix
WithClientInterceptor(fn)	Add client-side interceptor
WithClientJetStream(js)	Enable KV/Object Store reads

Timeout Precedence

From highest to lowest priority:

1. Runtime — WithTimeout(60s) on registration
2. Endpoint-level — option (natsmicro.endpoint) = { timeout: {seconds: 10} }
3. Service-level — option (natsmicro.service) = { timeout: {seconds: 30} }
4. Default — No timeout (0)

Proto Import

Add the dependency to your buf.yaml:

deps:
  - buf.build/toyz/natsmicro

Then import in your .proto files:

import "natsmicro/options.proto";

All options are defined in extensions/proto/natsmicro/options.proto.