RFC-0053：Epitaphs

「這是你的伺服器」

摘要

本提案的目標是讓伺服器在 關閉連線，讓您知道連線為何 已打烊。雖然 八爪族 的某些部分，但尚未實作這些部分。

提振精神

目前，伺服器無法以標準方式 連線已關閉這等同於 確保錯誤處理程序會歸開發人員所有。開發人員可以 並在訊息中導入特殊的錯誤處理方式，或者 忽略錯誤處理機制 (並承擔無法診斷的錯誤)。

其中一個使用案例就是伺服器大多為錯誤發生時，如果伺服器發生錯誤， 所有連至用戶端的連線都已關閉。在此情況下，開發人員希望 一般用途的錯誤回報機制，因為所有對方法的有效呼叫 就會發生相同的錯誤宣告可能性 既麻煩又麻煩。

這個 FTP 沒有提供詳盡的錯誤回報給 以注意力機制為基礎具體來說，這項技術能夠傳達大量細節 (包括詳細訊息、處理程序狀態或傳播原因) 連線結尾超出範圍

而且沒有定義一組常見的錯誤代碼。

設計

這份提案修改了線路格式、原文語言和第一類 語言繫結

傳輸格式

電線格式規格目前有 Epitaphs 部分的部分。這個區段 將修訂如下：

Epitaph (Control Message Ordinal 0xFFFFFFFF)

An epitaph is a message with ordinal **0xFFFFFFFF**.  A server may send an
epitaph as the last message prior to closing the connection, to provide an
indication of why the connection is being closed.  No further messages may be
sent through the channel after the epitaph.  Epitaphs are not sent from clients
to servers.

When a client receives an epitaph message, it can assume that it has received
the last message, and the channel is about to be closed. The contents of the
epitaph message explain the disposition of the channel.

The epitaph contains an error status.  The error status of the epitaph is stored
in the reserved uint32 of the message header.  The reserved word is treated as
being of type **zx_status_t**: negative numbers are reserved for system error
codes, positive numbers are reserved for application error codes, and ZX_OK is
used to indicate normal connection closure.  The message is otherwise empty.

原文語言

原文語言規格目前有一個 省略符號。 將會正確更新。

頭等艙語言繫結

實作時要考量到傳送 Epitaph 訊息時 應該是在帳戶關閉前的最後一則訊息。如果發生錯誤， 不同語言的處理方式，例如透過傳送錯誤 C/C++ 中的程式碼，Result<t, e="">和 Dart 中的例外狀況)。</t,>

我們將在 C 繫結中新增 fidl_epitaph_write(管道, zx_status_t) 方法， 以及 fidl_epitaph_t 類型

我們會在原始 C 繫結中新增下列說明文件 繫結：

fidl_epitaph_write

Declared in lib/fidl/epitaph.h, defined in epitaph.c.

This function sends an epitaph with the given error number down the given
channel.  An epitaph is a special message, with ordinal 0xFFFFFFFF, which
contains an error code.  The epitaph must be the last thing sent down the
channel before it is closed.

C 異動的 CL：https://fuchsia-review.googlesource.com/c/zircon/+/178250

我們會變更 C++ 繫結，以便執行下列操作：

fidl::Binding 會在收到 Epitaph 後立即關閉管道。

開發人員可以使用 fidl::Binding::Close 關閉管道

系統會透過 set_error_handler().我們將新增一個 error_handler 變體，採用 使用代表錯誤代碼的 int 變數，並移除 現有的連結日後可能就要採取「合理的預設值」工作錯誤 處理常式中，但目前我們還不清楚這究竟是什麼。

這個管道的所有待處理讀取都會傳回 ZX_ERR_PEER_CLOSED。

C++ 繫結的 CL：https://fuchsia-review.googlesource.com/c/garnet/+/177939

需要更新其他繫結，包括 Dart、Rust 和 Go。

說明文件和範例

我們會按照上一節的說明更新說明文件。

開發人員指南

惡意程式碼的目的是讓伺服器能夠 向用戶端說明管道處理方式和請求 檢查是否已變更過

本節說明 Epita 的預期行為和用途。

1. 司機訊息只會從伺服器傳送至用戶端，不會在 再往其他方向行駛。如果已傳送，請務必輸入伺服器傳送至該位址的最後一封郵件 再由用戶端啟動。

2. 用戶端收到 Epitaph 訊息時，必須立即結束 管道。不得嘗試閱讀 可能是由不符合規定的伺服器實作所傳送。

3. 當用戶端觀察到對等互連完成，但沒有收到邀請時： 它必須如收到 ZX_ERR_PEER_CLOSED 副詞一樣繼續； 這兩種狀態在語意上是相等的

4. 伺服器應在ZX_OK 通訊協定管道連結到其通訊端， 指定的成功結束狀態

   a. 範例：當用戶端在代表 個別資料庫交易，伺服器應該會嘗試套用 要求的變更。如果成功，伺服器必須傳送 ZX_OK 憑證 再關閉管道客戶可合理解釋 ZX_OK 號表示交易成功 。

   b. 計數器範例：許多通訊協定未指定成功的端 州；用戶端應能連上伺服器並發出 在這段時間內，應用程式不受限且沒有限制對等的關閉次數， 用戶端就會關閉自己的管道在這種情況下， 伺服器關閉它的結束狀態會構成異常的結束狀態， 伺服器一律不應傳送 ZX_OK 符號。

5. 伺服器可能會在結尾ZX_OK 管道。 成功結束狀態我們建議的慣例如下：

   a. 如果伺服器因用戶端向用戶端傳送 FIDL 訊息的格式有誤，應傳送 ZX_ERR_INVALID_ARGS 憑證。

   b. 如果伺服器因用戶端向用戶端傳送 當前狀態無效的要求，則應將 ZX_ERR_BAD_STATE 號縮寫。

   c. 用戶端出現連線時，無法連上伺服器 (例如無法啟動) 是嘗試透過服務探索機制 與此伺服器建立連線 應傳送 ZX_ERR_UNAVAILABLE 副詞。(另請參閱此草圖)。

   d.如果伺服器因故無法繼續提供通訊協定 未回應用戶端執行的動作 (例如關機或 所以不需要傳送任何八位詞用戶端 將此視為 ZX_ERR_PEER_CLOSED。

   e. 如果伺服器遇到應用程式特定錯誤，應將 應用程式定義的錯誤代碼舉例來說，如果伺服器控制 檔案系統，而使用者嘗試執行不允許寫入的行為 執行時，可能會要求關閉連線時發生錯誤。

   f.請注意，這份清單僅列出部分示例。伺服器可能會根據 或適當。一如往常，我們建議 FIDL 作者務必明確記錄 包括通訊協定可能傳回的錯誤，包括省略符號。

回溯相容性

FIDL 文件目前指出 0x80000001 是 先生所說。我們正在將其變更為 0xFFFFFFFF，因為 IO 正在使用 0x80000001。 目前還沒有使用 0x80000001 的 Epitaph 語言。否則， 不是回溯相容性問題

成效

不適用

安全性

不適用。

測試

此功能的單元測試會新增至適當的 FIDL 繫結。更新後 每個支援的 FIDL 繫結都會獲得支援，因此應針對 FIDL 相容性測試。

缺點、替代方案和未知

我們考慮提出含有 Epitaph 的 System 介面 事件，這個事件就是所有其他介面訊息的父項。Epitaphs, 開啟 而不提供這類重大變更目前還有兩個 實作過程中會遇到的難題首先，衍生類型目前無效 但內容通常很快就會改變接著，由於這個提案 而 FIDL 剖析器 / 產生器則取決於執行階段， 如果在執行階段使用系統訊息，就會導致 依附元件

這項 FTP 帶來的 API 變更將不會妨礙 Epitaph 支援 這類訊息會歸入日後的系統訊息

有個想法開始浮現一個概念，那就是將一些口腔處理結合到源頭 語言，讓 zx_status 標記對應為 FIDL 定義的列舉。 這個問題已延後到日後的工作中。

建議的實作方式為兒童不宜。如果某個執行緒撰寫了一則訊息 與另一個關閉管道的執行緒同時複製，可寫出這個主詞 其他執行緒訊息之前，但在呼叫 zx_handle_close()。替代方案包括鎖定管道 明確的系統呼叫我們將從執行緒不安全的版本開始 進一步認識題目領域。