Rust — 服务端 API

服务端 API 负责绑定 transport、accept session、接收 submit 和控制消息，并发送 result、progress、流控反馈、object/cache event 和 close ack。

工作流

构造 NnrpServerOptions，提供一个应用 endpoint 和一个 provider route set。
注册本次部署编译进来的 transport provider。
使用 NnrpServer::listen 监听；Auto/Prefer 原子打开全部 eligible route。
使用 NnrpServer::accept 接收 session。
使用 receive_submit 接收任务，或分派 await_event。
通过返回的 NnrpServerOperation 发送输出。
使用 receive_runtime_control 接收运行时控制帧。
显式关闭 session。

`NnrpServer::listen`

rust

let options = NnrpServerOptions {
    endpoint: "nnrp://localhost/runtime/default".parse()?,
    provider_routes: ServerProviderRoutes::from([
        (
            TransportId::Ipc,
            ServerProviderRoute::at("unix:///run/nnrp/runtime.sock".parse()?),
        ),
    ]),
    transport_policy: TransportPolicy::PreferIpc,
    session: NnrpServerConfig::default(),
};

let server = NnrpServer::listen(
    options,
    [Arc::new(IpcProvider::default()), Arc::new(TcpProvider::default())],
).await?;

返回的 NnrpServer 是一个原子 listener set 上的逻辑 server。Auto/Prefer 打开全部 eligible 已安装 route， Force 只打开指定 route；任一必需 bind 失败都关闭本次调用已打开的全部 listener。accept 在整个集合上等待，每个已接受 session 最终只接管一条 carrier connection。

`NnrpServerOptions`

字段	类型	必填	说明
`endpoint`	`NnrpEndpoint`	是	用户侧 `nnrp://` 或 `nnrps://` endpoint。
`provider_routes`	`ServerProviderRoutes`	否	按 carrier 隔离的 bind locator 与 server-security 配置。
`transport_policy`	`TransportPolicy`	否	listener set eligibility policy。
`session`	`NnrpServerConfig`	否	与 transport 无关的 accepted-session 默认值。

ServerProviderRoutes 是 BTreeMap<TransportId, ServerProviderRoute>。ServerProviderRoute 精确包含 provider_endpoint: Option<ProviderEndpoint> 与 security: Option<ServerTransportSecurity>。单数 provider endpoint 或 role-wide security 不属于 NnrpServerOptions。

ServerTransportSecurity 精确包含 certificate_der: Vec<u8> 与 private_key_pkcs8_der: Vec<u8>；两个 owned byte vector 都必须非空。提供该值会为 TCP 启用 TLS，QUIC 与 native WSS route 必须提供。

为未安装 provider 的 transport 提供 route 时，该 candidate 保留为 local-unavailable。已安装、原本 eligible 的 provider 缺少必需 locator 属于 listen 配置错误，并触发原子回滚。

低层 `NnrpServer::bind_tcp`

参数	类型	必填	取值范围	说明
`addr`	`impl tokio::net::ToSocketAddrs`	是	Socket address	本地 TCP bind address。
`config`	`NnrpServerConfig`	是	与 transport 无关	Server runtime 配置。

返回	错误
`Result<NnrpServer, RuntimeError>`	Bind、listener、transport 或配置错误。

rust

let config = NnrpServerConfig::default();
let server = NnrpServer::bind_tcp("127.0.0.1:4433", config).await?;

这个方法为 provider 测试、诊断和受控单 carrier 部署创建单 listener 逻辑集合。生产多 provider 宿主使用 listen。

Provider Bind

Provider	Package	常用方法	说明
`TcpProvider`	`nnrp-transport-tcp`	`bind(addr, config)`	TCP listener。
`QuicProvider`	`nnrp-transport-quic`	`bind(endpoint_config, config)`	带证书和 ALPN 配置的 QUIC listener。
`IpcProvider`	`nnrp-transport-ipc`	`bind(endpoint, config)`	Unix socket 或 Windows named pipe listener。
`WebSocketProvider`	`nnrp-transport-websocket`	`bind(endpoint, config)`	原生 WebSocket binary listener。

`NnrpServer::from_listener`

参数	类型	必填	取值范围	说明
`listener`	`L: FramedListener + 'static`	是	任意 framed listener	自定义或 provider 创建的 listener。
`config`	`NnrpServerConfig`	是	与 transport 无关	Runtime 配置。

返回	错误
`Result<NnrpServer, RuntimeError>`	Listener kind 不匹配或配置无效。

`NnrpServer::accept`

参数	类型	必填	取值范围	说明
无	-	-	-	接收一个 peer 并打开一个 runtime session。

返回	错误
`Result<NnrpServerSession, RuntimeError>`	Accept、session-open 拒绝或 transport 错误。

每个已接受 session 都公开 active_transport_id() -> TransportId。这个值标识实际接受 carrier 的 listener，并且必须与协商得到的 active_transport_id 一致，不能从 listener preference 顺序推断。

bound_provider_endpoints() -> &BTreeMap<TransportId, ProviderEndpoint> 返回逻辑集合中每个 listener 的实际 endpoint，包括操作系统分配的端口。Provider listener 的致命失败会让逻辑 server 失败并关闭其余 listener； peer handshake 拒绝不会。

`NnrpServerSession::await_event`

rust

pub async fn await_event(&mut self) -> Result<NnrpServerEvent, RuntimeError>

按 wire 顺序返回下一条 submit、control、runtime-object、cache、recovery 或 close event。这是面向应用的服务端接收 API。原生 FFI binding 可以在内部按有界批次轮询事件，但必须把批次重新投影为这个有序单事件契约。

`NnrpServerSession::receive_submit`

参数	类型	必填	取值范围	说明
无	-	-	-	读取下一个 submit frame。

返回	错误
`Result<NnrpServerOperation, RuntimeError>`	Transport、解析、生命周期或 unexpected-message 错误。

rust

let operation = session.receive_submit().await?;

receive_submit 是仅在当前状态只允许 submit 流量时使用的窄化便利接口。允许 control、object、cache 和 close frame 交错的 host 应调用 await_event，并分派返回的 NnrpServerEvent。

`NnrpServerOperation` 回复

参数	类型	必填	取值范围	说明
`metadata`	`ResultPushMetadata`	是	有效 result metadata	Result status 与 timing metadata。
`body`	`Vec<u8>`	是	可为空	序列化 result body。

返回	错误
`Result<(), RuntimeError>`	生命周期、序列化或 transport 错误。

rust

operation
    .send_result(&mut session, ResultPushMetadata::default(), output)
    .await?;

方法	参数	返回	说明
`send_result`	session、metadata、body	`Result<(), RuntimeError>`	发送该 operation 唯一的终态结果。
`send_result_drop`	session、metadata、diagnostic	`Result<(), RuntimeError>`	发送该 operation 的终态丢弃原因。
`send_progress`	session、metadata、body	`Result<(), RuntimeError>`	发送该 operation 的非终态进度。
`send_partial_result`	session、metadata、body	`Result<(), RuntimeError>`	发送该 operation 的增量结果字节。

operation 会在写出前校验 session ownership 和 operation_id。它不可克隆，并且只允许一个终态方法成功。 NnrpServerSession 不暴露任何绕过 operation ownership 的回复方法。

收到终态 lifecycle event 不会在终态回复成功前使已持有的 operation 失效。operation 会保持可回复，直到终态回复成功或 session 关闭；继续 poll 其他 event 不得改变这段生命周期。

Runtime Control Methods

方法	参数	返回	说明
`receive_cancel`	无	`Result<CancelMetadata, RuntimeError>`	接收 cancellation。
`receive_runtime_control`	无	`Result<NnrpRuntimeControl, RuntimeError>`	接收带 metadata 和 body 的 Preview4 通用控制帧。
`send_backpressure`	metadata	`Result<(), RuntimeError>`	通知 client 降速。
`receive_pressure_update`	无	`Result<PressureUpdateMetadata, RuntimeError>`	接收 client pressure state。
`send_capability`	metadata	`Result<(), RuntimeError>`	发送 cost/preference/limit 信息。
`send_route_hint`	metadata	`Result<(), RuntimeError>`	发送执行或路由 hint。

Object And Cache Methods

方法	参数	返回	说明
`send_object_declare`	metadata, body	`Result<(), RuntimeError>`	声明 runtime object。
`send_object_ref`	metadata, body	`Result<(), RuntimeError>`	引用已有 object。
`send_object_release`	metadata, body	`Result<(), RuntimeError>`	释放 object reference。
`send_object_delta`	metadata, body	`Result<(), RuntimeError>`	发送 object delta bytes。
`send_cache_reference`	metadata, body	`Result<(), RuntimeError>`	发送 cache hit/reference。
`send_cache_miss`	metadata, body	`Result<(), RuntimeError>`	报告 cache miss。
`send_cache_invalidate`	metadata, body	`Result<(), RuntimeError>`	失效 cache entry。

Lifecycle Methods

方法	参数	返回	说明
`receive_close`	无	`Result<SessionCloseMetadata, RuntimeError>`	等待 client close。
`ack_close`	close metadata	`Result<(), RuntimeError>`	确认 close。
`close`	无	`Result<(), RuntimeError>`	关闭 server session。

`NnrpServerConfig`

字段	类型	默认值	说明
`supported_profiles`	`Vec<u16>`	标准 token profile	接受的 profiles。
`supported_cache_objects`	`Vec<CacheObjectKind>`	空	接受的 cache object kinds。
`schema_registry`	`SchemaRegistry`	标准 registry	接受的 schemas。
`max_in_flight_operations`	`u16`	`4`	In-flight operation 限制。
`granted_operation_credit`	`u16`	`2`	初始 operation credit。
`lease_ttl_ms`	`u32`	`30000`	Lease TTL。
`resume_window_ms`	`u32`	`120000`	Resume window。
`application_policy`	`Arc<dyn NnrpServerPolicy>`	Allow-all	应用层校验策略。

`NnrpServerOperation`

字段	类型	说明
`frame_id`	`u32`	Submitted frame id。
`operation_id`	`u64`	Submit metadata 中的非零 operation identity。
`submit`	`NnrpRuntimeEvent`	完整持有的 `FRAME_SUBMIT` 事件，包括 metadata 和 body。

WARNING

receive_submit 是选择性接口。如果 submit、control、object、cache、lifecycle 和 close 会交错出现，应使用 await_event；receive_submit 会把跳过的事件保留在同一个 session queue 中，绝不会丢弃。

Rust — 服务端 API ​

工作流 ​

NnrpServer::listen ​

NnrpServerOptions ​

低层 NnrpServer::bind_tcp ​

Provider Bind ​

NnrpServer::from_listener ​

NnrpServer::accept ​

NnrpServerSession::await_event ​

NnrpServerSession::receive_submit ​

NnrpServerOperation 回复 ​

Runtime Control Methods ​

Object And Cache Methods ​

Lifecycle Methods ​

NnrpServerConfig ​

NnrpServerOperation ​

Rust — 服务端 API

工作流

`NnrpServer::listen`

`NnrpServerOptions`

低层 `NnrpServer::bind_tcp`

Provider Bind

`NnrpServer::from_listener`

`NnrpServer::accept`

`NnrpServerSession::await_event`

`NnrpServerSession::receive_submit`

`NnrpServerOperation` 回复

Runtime Control Methods

Object And Cache Methods

Lifecycle Methods

`NnrpServerConfig`

`NnrpServerOperation`