From e524f05aa9f7b1cc18b6cf8165e6fde0913b55c7 Mon Sep 17 00:00:00 2001
From: Nick Mathewson <nickm@torproject.org>
Date: Thu, 13 Apr 2023 10:49:20 -0400
Subject: [PATCH] rpc spec: define method namespacing.

Closes #822
---
 Cargo.lock                      |  2 +-
 doc/dev/notes/rpc-meta-draft.md | 34 ++++++++++++++++++++++++++++-----
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index d5958a119..0b4ee7364 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -3098,7 +3098,7 @@ checksum = "bcec881020c684085e55a25f7fd888954d56609ef363479dc5a1305eb0d40cab"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.12",
+ "syn 2.0.14",
 ]
 
 [[package]]
diff --git a/doc/dev/notes/rpc-meta-draft.md b/doc/dev/notes/rpc-meta-draft.md
index 2fee04cd8..cbb4880c5 100644
--- a/doc/dev/notes/rpc-meta-draft.md
+++ b/doc/dev/notes/rpc-meta-draft.md
@@ -219,11 +219,8 @@ obj
 
 method
 : A string naming the method to invoke. It is required.
-  Method names are namespaced;
-  For now, we commit to not using any method name
-  beginning with "x-" or "X-".
-  (If you want to reserve any other prefix,
-  we can eventually start a registry or something.)
+  Method names are namespaced; see
+  "Method Namespacing" below.
 
 params
 : A JSON object describing the parameters for the method.
@@ -307,6 +304,33 @@ Any given response will have exactly one of
 > TODO: Specify our error format to be the same as,
 > or similar to, that used by JSON-RPC.
 
+
+#### Method namespacing
+
+Any method name containing a colon belongs to a namespace.
+The namespace of a method is everything up to the first colon.
+(For example, the method name `arti:connect`
+is in the namespace `arti`.
+The method name `gettype` is not in any namespace.)
+
+Only this spec MAY declare non-namespaced methods.
+All methods defined elsewhere SHOULD be in a namespace.
+
+Right now, the following namespaces are reserved:
+
+* `arti` — For use by the Arti tor implementation project.
+* `auth` — Defined in this spec; for authenticating an initial session.
+
+To reserve a namespace, open a merge request to change the list above.
+
+Namespaces starting with `x-` will never be allocated.
+They are reserved for experimental use.
+
+Method names starting with `x-` indicate
+experimental or unstable status:
+any code using them should expect to be unstable.
+
+
 ### Errors
 
 Errors are reported as responses with an `error` field (as above).