NATS文档
  • 欢迎
  • 发行备注
    • 最新情况
      • NATS 2.2
      • NATS 2.0
  • NATS 概念
    • 概览
      • 比较 NATS
    • 什么是NATS
      • 演练安装
    • 基于主题的消息
    • 核心NATS
      • 发布和订阅
        • 发布/订阅演 练
      • 请求和响应
        • 请求/响应 演练
      • 队列组
        • 队列 演练
    • JetStream
      • 流
      • 消费者
        • 示例
      • JetStream 演练
      • 键值对存储
        • 键值对存储演练
      • 对象存储
        • 对象存储演练
    • 主题映射与分区
    • NATS服务器基础架构
      • NATS部署架构适配
    • 安全
    • 连接性
  • 使用 NATS
    • NATS工具
      • nats
        • nats基准测试
      • nk
      • nsc
        • 基础
        • 流
        • 服务
        • 签名密钥
        • 撤销
        • 管理操作
      • nats-top
        • 教程
    • 用NATS开发
      • 一个NATS应用的解剖
      • 连接
        • 连接到默认服务器
        • 连接到特定服务器
        • 连接到群集
        • 连接名称
        • 用用户名和密码做认证
        • 用令牌做认证
        • 用NKey做认证
        • 用一个可信文件做认证
        • 用TLS加密连接
        • 设置连接超时
        • 乒乓协议
        • 关闭响应消息
        • 杂技功能
        • 自动恢复
          • 禁用自动重连
          • 设置自动重新连接的最大次数
          • 随机
          • 重连尝试之间暂停
          • 关注重连事件
          • 重连尝试期间缓存消息
        • 监视连接
          • 关注连接事件
          • 低速消费者
      • 接收消息
        • 同步订阅
        • 异步订阅
        • 取消订阅
        • N个消息后取消订阅
        • 回复一个消息
        • 通配符订阅
        • 队列订阅
        • 断开连接前清除消息
        • 接收结构化数据
      • 发送消息
        • 包含一个回复主题
        • 请求回复语义
        • 缓存刷入和乒
        • 发送结构化数据
      • JetStream
        • 深入JetStream模型
        • 管理流和消费者
        • 消费者详情
        • 发布到流
        • 使用键值对存储
        • 使用对象存储
      • 教程
        • 用go做个自定义拨号器
  • 运行一个NATS服务
    • 安装、运行和部署NATS服务
      • 安装一个NATS服务
      • 运行和部署一个NATS服务
      • Windows服务
      • 信号
    • 环境约束
    • NATS和Docker
      • 教程
      • Docker Swarm
      • Python 和 NGS 运行在Docker
      • JetStream
    • NATS和Kubernetes
      • 用Helm 部署NATS
      • 创建一个Kubernetes群集
      • NATS群集和认证管理
      • 用cfssl保护NATS群集
      • 用负载均衡来保护外部的NATS访问
      • 在Digital Ocean用Helm创建超级NATS群集
      • 使用Helm从0到K8S再到叶子节点
    • NATS服务的客户端
    • 配置 NATS服务
      • 配置 JetStream
        • 配置管理 Management
          • NATS管理命令行
          • 地形
          • GitHub Actions
          • Kubernetes控制器
      • 群集
        • 群集配置
        • JetStream 群集
          • 管理
      • 网关超级群集
        • 配置
      • 叶子节点
        • 配置
        • JetStream在叶子节点
      • 安全加固NATS
        • 使用 TLS
        • 认证
          • 令牌
          • 用户名/密码
          • TLS认证
            • 群集中的TLS认证
          • NKeys
          • 认证超时
          • 去中心化的 JWT 认证/授权
            • 使用解析器查找帐户
            • 内存解析器教程
            • 混合认证/授权安装
        • 授权
        • 基于账户的多租户
        • OCSP Stapling
      • 日志
      • 使用监控
      • MQTT
        • 配置
      • 配置主题映射
      • 系统事件
        • 系统时间和去中心化的JWT教程
      • WebSocket
        • 配置
    • 管理和监控你的NATS服务基础架构
      • 监控
        • 监控 JetStream
      • 管理 JetStream
        • 账号信息
        • 命名流,消费者和账号
        • 流
        • 消费者
        • 数据复制
        • 灾难回复
        • 加密Rest
      • 管理JWT安全
        • 深入JWT指南
      • 升级一个群集
      • 慢消费者
      • 信号
      • 跛脚鸭模式
  • 参考
    • 常见问题
    • NATS协议
      • 协议演示
      • 客户端协议
        • 开发一个客户端
      • NATS群集协议
      • JetStream API参考
  • 遗产
    • STAN='NATS流'
      • STAN概念
        • 和NATS的关系
        • 客户端连接
        • 频道
          • 消息日志
          • 订阅
            • 通常的
            • 持久化的
            • 队列组
            • 重新投递
        • 存储接口
        • 存储加密
        • 群集
          • Supported Stores
          • Configuration
          • Auto Configuration
          • Containers
        • Fault Tolerance
          • Active Server
          • Standby Servers
          • Shared State
          • Failover
        • Partitioning
        • Monitoring
          • Endpoints
      • Developing With STAN
        • Connecting to NATS Streaming Server
        • Publishing to a Channel
        • Receiving Messages from a Channel
        • Durable Subscriptions
        • Queue Subscriptions
        • Acknowledgements
        • The Streaming Protocol
      • STAN NATS Streaming Server
        • Installing
        • Running
        • Configuring
          • Command Line Arguments
          • Configuration File
          • Store Limits
          • Persistence
            • File Store
            • SQL Store
          • Securing
        • Process Signaling
        • Windows Service
        • Embedding NATS Streaming Server
        • Docker Swarm
        • Kubernetes
          • NATS Streaming with Fault Tolerance.
    • nats账号服务
      • Basics
      • Inspecting JWTs
      • Directory Store
      • Update Notifications
由 GitBook 提供支持
在本页
  • NATS Streaming Protocol
  • NATS streaming protocol conventions
  • NATS streaming protocol messages
  1. 遗产
  2. STAN='NATS流'
  3. Developing With STAN

The Streaming Protocol

上一页Acknowledgements下一页STAN NATS Streaming Server

最后更新于2年前

You can find a list of all supported client libraries . There are also links to community contributed clients.

In the event you would want to write your own NATS Streaming library, you could have a look at existing libraries to understand the flow. But you need to use to exchange protocols between the client and the server.

NATS Streaming Protocol

The NATS streaming protocol sits atop the core NATS protocol and uses . Protocol buffer messages are marshaled into bytes and published as NATS messages on specific subjects described below. In communicating with the NATS Streaming Server, the NATS request-reply pattern is used for all protocol messages that have a corresponding reply.

NATS streaming protocol conventions

Subject names: Subject names, including reply subject (INBOX) names, are case-sensitive and must be non-empty alphanumeric strings with no embedded whitespace, and optionally token-delimited using the dot character (.), e.g.:

FOO, BAR, foo.bar, foo.BAR, FOO.BAR and FOO.BAR.BAZ are all valid subject names

FOO. BAR, foo. .bar andfoo..bar are *not- valid subject names

Wildcards: NATS streaming does not support wildcards in subject subscriptions

Protocol definition: The fields of NATS streaming protocol messages are defined in the NATS streaming client .

NATS streaming protocol messages

The following table briefly describes the NATS streaming protocol messages.

Click the name to see more detailed information, including usage:

Protocols

Message Name
Sent By
Description

Client

Request to connect to the NATS Streaming Server

Server

Result of a connection request

Client

Request sent to subscribe and retrieve data

Server

Result of a subscription request

Client

Unsubscribe from a subject

Client

Publish a message to a subject

Server

An acknowledgement that a published message has been processed on the server

Server

A message from the NATS Streaming Server to a subscribing client

Client

Acknowledges that a message has been received

Client

Ping sent to server to detect connection loss

Server

Result of a Ping

Client

Request sent to close the connection to the NATS Streaming Server

Server

Result of the close request

The following sections explain each protocol message.

ConnectRequest

Description

More advanced libraries can set the protocol to 1 and send a connection ID which in combination with ping interval and ping max out allows the library to detect that the connection to the server is lost.

This request is published to a subject comprised of the <discover-prefix>.cluster-id. For example, if a NATS Streaming Server was started with a cluster-id of mycluster, and the default prefix was used, the client publishes to _STAN.discover.mycluster

Message Structure

  • clientID: A unique identifier for a client

  • heartbeatInbox: An inbox to which the NATS Streaming Server will send heartbeats for the client to process

  • protocol: Protocol the client is at

  • connID: Connection ID, a way to uniquely identify a connection (no connection should ever have the same)

  • pingInterval: Interval at which client wishes to send PINGs (expressed in seconds)

  • pingMaxOut: Maximum number of PINGs without a response after which the connection can be considered lost

ConnectResponse

Description

After a ConnectRequest is published, the NATS Streaming Server responds with this message on the reply subject of the underlying NATS request. The NATS Streaming Server requires the client to make requests and publish messages on certain subjects (described above), and when a connection is successful, the client saves the information returned to be used in sending other NATS streaming protocol messages. In the event the connection was not successful, an error is returned in the error field.

Message Structure

  • pubPrefix: Prefix to use when publishing

  • subRequests: Subject used for subscription requests

  • unsubRequests: Subject used for unsubscribe requests

  • closeRequests: Subject for closing a connection

  • error: An error string, which will be empty/omitted upon success

  • subCloseRequests: Subject to use for subscription close requests

  • pingRequests: Subject to use for PING requests

  • pingInterval: Interval at which client should send PINGs (expressed in seconds).

  • pingMaxOut: Maximum number of PINGs without a response after which the connection can be considered lost

  • protocol: Protocol version the server is at

  • publicKey: Reserved for future use

SubscriptionRequest

Description

Message Structure

  • subject: Formal subject to subscribe to, e.g. foo.bar

  • qGroup: Optional queue group

  • inbox: Inbox subject to deliver messages on

  • maxInFlight: Maximum inflight messages without an acknowledgement allowed

  • ackWaitInSecs: Timeout for receiving an acknowledgement from the client

  • durableName: Optional durable name which survives client restarts

  • startPosition: An enumerated type specifying the point in history to start replaying data

  • startSequence: Optional start sequence number

  • startTimeDelta: Optional start time

StartPosition enumeration

  • NewOnly: Send only new messages

  • LastReceived: Send only the last received message

  • TimeDeltaStart: Send messages from duration specified in the startTimeDelta field.

  • SequenceStart: Send messages starting from the sequence in the startSequence field.

  • First: Send all available messages

SubscriptionResponse

Description

Message Structure

  • ackInbox: subject the client sends message acknowledgements to the NATS Streaming Server

  • error: error string, empty/omitted if no error

UnsubscribeRequest

Description

The UnsubscribeRequest closes or unsubcribes the subscription from the specified subject. The inbox specified is the inbox returned from the NATS Streaming Server in the SubscriptionResponse. Depending on which subject this request is sent, the action will result in close (if sent to subject subCloseRequests) or unsubscribe (if sent to subject unsubRequests)

Message Structure

  • subject: Subject for the subscription

  • inbox: Inbox subject to identify subscription

  • durableName: Optional durable name which survives client restarts

PubMsg

Description

Message Structure

  • guid: a guid generated for this particular message

  • subject: subject

  • data: payload

  • connID: Connection ID. For servers that know about this field, clientID can be omitted

PubAck

Description

The PubAck message is an acknowledgement from the NATS Streaming Server that a message has been processed. The message arrives on the subject specified on the reply subject of the NATS message the PubMsg was published on. The GUID is the same GUID used in the PubMsg being acknowledged. If an error string is present, the message was not persisted by the NATS Streaming Server and no guarantees regarding persistence are honored. PubAck messages may be handled asynchronously from their corresponding PubMsg in the client.

Message Structure

  • guid: GUID of the message being acknowledged by the NATS Streaming Server

  • error: An error string, empty/omitted if no error

MsgProto

Description

Message Structure

  • sequence: Globally ordered sequence number for the subject's channel

  • subject: Subject

  • data: Payload

  • timestamp: Time the message was stored in the server. Represented as Unix time (number of nanoseconds elapsed since January 1, 1970 UTC)

  • redelivered: Flag specifying if the message is being redelivered

Ack

Description

Message Structure

  • subject: Subject of the message being acknowledged

  • sequence: Sequence of the message being acknowledged

Ping

Description

Message Structure

  • connID: The connection ID

PingResponse

Description

This is a response from the server to a Ping from the client. If the content is not empty, it will be the error indicating to the client why the connection is no longer valid.

Message Structure

  • error: Error string, empty/omitted if no error

CloseRequest

Description

Message Structure

CloseResponse

Description

The CloseResponse is sent by the NATS Streaming Server on the reply subject of the CloseRequest NATS message. This response contains any error that may have occurred with the corresponding close call.

Message Structure

  • error: error string, empty/omitted if no error

A connection request is sent when a streaming client connects to the NATS Streaming Server. The connection request contains a unique identifier representing the client, and an inbox subject the client will listen on for incoming heartbeats. The identifier must be unique; a connection attempt with an identifier currently in use will fail. The inbox subject is the subject where the client receives incoming heartbeats, and responds by publishing an empty NATS message to the reply subject, indicating it is alive. The NATS Streaming Server will return a message to the reply subject specified in the NATS request message.

A SubscriptionRequest is published on the subject returned in the subRequests field of a , and creates a subscription to a subject on the NATS Streaming Server. This will return a message to the reply subject specified in the NATS protocol request message.

clientID: Client ID originally provided in the

The SubscriptionResponse message is the response from the SubscriptionRequest. After a client has processed an incoming message, it must send an acknowledgement to the ackInbox subject provided here.

clientID: Client ID originally provided in the

The PubMsg protocol message is published from a client to the NATS Streaming Server. The GUID must be unique, and is returned in the message to correlate the success or failure of storing this particular message.

clientID: Client ID originally provided in the

The MsgProto message is received by client from the NATS Streaming Server, containing the payload of messages sent by a publisher. A MsgProto message that is not acknowledged with an message within the duration specified by the ackWaitInSecs field of the subscription request will be redelivered.

An Ack message is an acknowledgement from the client that a message has been considered received. It is published to the ackInbox field of the .

A Ping message is sent to the server at configured interval to check that the connection ID is still valid. This should be used only if client is at protocol 1, and has sent a connID in the protocol.

A CloseRequest message is published on the closeRequests subject from the , and notifies the NATS Streaming Server that the client connection is closing, allowing the server to free up resources. This message should always be sent when a client is finished using a connection.

clientID: Client ID originally provided in the

here
Google Protocol Buffers
Google's Protocol Buffers
protocol file
ConnectResponse
Back to table
Back to table
ConnectResponse
SubscriptionResponse
ConnectRequest
Back to table
MsgProto
Back to table
ConnectRequest
Back to table
PubAck
ConnectRequest
Back to table
Back to table
Ack
Back to table
MsgProto
SubscriptionResponse
Back to table
ConnectRequest
Back to table
Back to table
ConnectResponse
ConnectRequest
Back to table
Back to table
ConnectRequest
ConnectResponse
SubscriptionRequest
SubscriptionResponse
UnsubscribeRequest
PubMsg
PubAck
MsgProto
Ack
Ping
PingResponse
CloseRequest
CloseResponse