Comprehensive URI Template syntax guide

Added a new documentation page explaining RFC 6570 URI Template syntax
and its usage throughout Fedify's routing system. The guide covers:

- Different expansion types ({var}, {+var}, {/var}, {?var}, {&var})
- When to use each expansion type
- Common use cases for actors, collections, inbox listeners, and objects
- Common pitfalls like double-encoding with URI identifiers
- Decision guide and troubleshooting tips

Also added cross-references from actor.md, collections.md, inbox.md,
and object.md to help users choose the appropriate expansion syntax
for their identifiers.

Close #417

Author: dahlia

docs/.vitepress/config.mts

@@ -70,6 +70,7 @@ const MANUAL = {
     { text: "Access control", link: "/manual/access-control.md" },
     { text: "WebFinger", link: "/manual/webfinger.md" },
     { text: "NodeInfo", link: "/manual/nodeinfo.md" },
+    { text: "URI Template", link: "/manual/uri-template.md" },
     { text: "Pragmatics", link: "/manual/pragmatics.md" },
     { text: "Key–value store", link: "/manual/kv.md" },
     { text: "Message queue", link: "/manual/mq.md" },

docs/manual/actor.md

@@ -66,6 +66,13 @@ follows the [URI Template] specification.
 > See the [next section](#decoupling-actor-uris-from-webfinger-usernames)
 > for details.
 
+> [!NOTE]
+> The URI Template syntax supports different expansion types like `{identifier}`
+> (simple expansion) and `{+identifier}` (reserved expansion).  Choosing the
+> right expansion type is important to avoid encoding issues.  See the
+> [*URI Template* guide](./uri-template.md) for details on when to use
+> each type.
+
 [actors]: https://www.w3.org/TR/activitystreams-core/#actors
 [activities]: https://www.w3.org/TR/activitystreams-core/#activities
 [URI Template]: https://datatracker.ietf.org/doc/html/rfc6570

docs/manual/collections.md

@@ -47,6 +47,13 @@ Each actor has its own outbox collection, so the URI pattern of the outbox
 dispatcher should include the actor's `{identifier}`.  The URI pattern syntax
 follows the [URI Template] specification.
 
+> [!NOTE]
+> The URI Template syntax supports different expansion types like `{identifier}`
+> (simple expansion) and `{+identifier}` (reserved expansion).  If your
+> identifiers contain URIs or special characters, you may need to use
+> `{+identifier}` to avoid double-encoding issues.  See the
+> [*URI Template* guide](./uri-template.md) for details.
+
 Since the outbox is a collection of activities, the outbox dispatcher should
 return an array of activities.  The following example shows how to construct
 an outbox collection:
@@ -1438,14 +1445,14 @@ federation
     async (ctx, values, cursor) => {
       // If a whole collection is requested, return null to use pagination
       if (cursor == null) return null;
-      
+
       // Work with the database to find bookmarked posts
       const { posts, nextCursor } = await getBookmarkedPostsByUserId(
         values.identifier,
         cursor === "" ? null : cursor,
         10
       );
-      
+
       // Convert posts to Article objects
       const items = posts.map(post =>
         new Article({
@@ -1454,7 +1461,7 @@ federation
           content: post.content,
         })
       );
-      
+
       return { items, nextCursor };
     }
   )
@@ -1513,21 +1520,21 @@ federation
     async (ctx, values, cursor) => {
       // Implementation is the same as regular collections
       if (cursor == null) return null;
-      
+
       const { posts, nextCursor } = await getBookmarkedPostsByUserId(
         values.identifier,
         cursor === "" ? null : cursor,
         10
       );
-      
+
       const items = posts.map(post =>
         new Article({
           id: new URL(`/posts/${post.id}`, ctx.url),
           summary: post.title,
           content: post.content,
         })
       );
-      
+
       return { items, nextCursor };
     }
   )
@@ -1578,12 +1585,12 @@ federation
         values.category,
         cursor === "" ? null : cursor
       );
-      
+
       const items = posts.map(post => new Note({
         id: new URL(`/posts/${post.id}`, ctx.url),
         content: post.content,
       }));
-      
+
       return { items, nextCursor };
     }
   )
@@ -1603,9 +1610,9 @@ const ctx = null as unknown as Context<void>;
 ctx.getCollectionUri("bookmarks", { identifier: "alice" })
 
 // For a collection with multiple parameters:
-ctx.getCollectionUri("category-posts", { 
-  identifier: "alice", 
-  category: "technology" 
+ctx.getCollectionUri("category-posts", {
+  identifier: "alice",
+  category: "technology"
 })
 ~~~~
 
@@ -1654,28 +1661,28 @@ federation
     "/users/{identifier}/private-bookmarks",
     async (ctx, values, cursor) => {
       if (cursor == null) return null;
-      
+
       const { posts, nextCursor } = await getBookmarkedPostsByUserId(
         values.identifier,
         cursor === "" ? null : cursor
       );
-      
+
       const items = posts.map(post =>
         new Article({
           id: new URL(`/posts/${post.id}`, ctx.url),
           summary: post.title,
           content: post.content,
         })
       );
-      
+
       return { items, nextCursor };
     }
   )
   .setFirstCursor(async (ctx, values) => "")
   .authorize(async (ctx, values, signedKey, signedKeyOwner) => {
     // Only allow access if the viewer is the owner of the bookmarks
     if (signedKeyOwner == null) return false;
-    
+
     const viewerId = await getActorIdentifier(signedKeyOwner.id);
     return await canAccessBookmarks(viewerId, values.identifier);
   });

docs/manual/inbox.md

@@ -82,6 +82,13 @@ and a callback function that takes a `Context` object and the activity object.
 Note that the `~InboxListenerSetters.on()` method can be chained to register
 multiple inbox listeners for different activity types.
 
+> [!NOTE]
+> The URI Template syntax supports different expansion types like `{identifier}`
+> (simple expansion) and `{+identifier}` (reserved expansion).  If your
+> identifiers contain URIs or special characters, you may need to use
+> `{+identifier}` to avoid double-encoding issues.  See the
+> [*URI Template* guide](./uri-template.md) for details.
+
 > [!WARNING]
 > Activities of any type that are not registered with
 > the `~InboxListenerSetters.on()` method are silently ignored.

docs/manual/object.md

@@ -53,6 +53,13 @@ an object dispatcher for the `Note` class and
 the `/users/{userId}/notes/{noteId}` path.  This pattern syntax follows
 the [URI Template] specification.
 
+> [!NOTE]
+> The URI Template syntax supports different expansion types like `{userId}`
+> (simple expansion) and `{+userId}` (reserved expansion).  If your
+> identifiers contain URIs or special characters, you may need to use
+> `{+userId}` to avoid double-encoding issues.  See the
+> [*URI Template* guide](./uri-template.md) for details.
+
 [objects]: https://www.w3.org/TR/activitystreams-core/#object
 [URI Template]: https://datatracker.ietf.org/doc/html/rfc6570