diff --git a/doc/dev/notes/rpc-meta-draft.md b/doc/dev/notes/rpc-meta-draft.md index c4d2ba55b..fc686da93 100644 --- a/doc/dev/notes/rpc-meta-draft.md +++ b/doc/dev/notes/rpc-meta-draft.md @@ -310,9 +310,12 @@ message or do anything with it besides display it to the end user. (This is generated by `tor_error::Report` or equivalant.) -arti_kinds +kinds : An array of Strings, each - denoting one of the members of `tor_error::ErrorKind`. + denoting a category of error. + Kinds defined by Arti will begin with the prefix + "arti:", and will + denote one of the members of [`tor_error::ErrorKind`]. If Arti renames an `ErrorKind`, the old name will be provided after the new name. @@ -361,9 +364,9 @@ code The `code` field is provided for JSON-RPC compatibility, and its use is not recommended. - Use `arti_kind` to distinguish error categories instead. + Use `kinds` to distinguish error categories instead. For example, instead of comparing `code` to `-32601`, - recognise `RpcMethodNotFound` in `arti_kinds`. + recognise `RpcMethodNotFound` in `kinds`. ``` code message meaning @@ -377,6 +380,8 @@ code message meaning We do not anticipate regularly extending this list of values. +[`tor_error::ErrorKind`]: https://docs.rs/tor-error/latest/tor_error/enum.ErrorKind.html + #### Example error response JSON document Note: this is an expanded display for clarity! @@ -388,7 +393,7 @@ to conform to jsonlines framing. "id" : "5631557cdce0caa0", "error" : { "message" : "Cannot connect to a local-only address without enabling allow_local_addrs", - "arti_kinds" : [ + "kinds" : [ "ForbiddenStreamTarget" ], "data" : { @@ -408,7 +413,7 @@ The differences are: it is dealt with at the framing layer (probably, by summarily closing the transport connection) - * The `arti_kind` field has been added, + * The `kinds` field has been added, and use of `code` is discouraged. * The `message` field may be less concise than JSON-RPC envisages.