From 342146eafd3adb97dc1151bce9f131ced647f871 Mon Sep 17 00:00:00 2001
From: Kegan Dougal <kegan@matrix.org>
Date: Fri, 20 Feb 2015 15:06:43 +0000
Subject: [PATCH] Add IRC bridge AS example.

---
 .../examples/application-services.rst         | 129 ++++++++++++++++++
 1 file changed, 129 insertions(+)
 create mode 100644 supporting-docs/examples/application-services.rst

diff --git a/supporting-docs/examples/application-services.rst b/supporting-docs/examples/application-services.rst
new file mode 100644
index 00000000..bde4531b
--- /dev/null
+++ b/supporting-docs/examples/application-services.rst
@@ -0,0 +1,129 @@
+Application Services
+====================
+
+This file contains examples of some application service
+
+IRC Bridge
+----------
+Pre-conditions:
+  - Server admin stores the AS token "T_a" on the home server.
+  - Home server has a token "T_h".
+  - Home server has the domain "hsdomain.com"
+
+1. Application service registration
+
+::
+  
+  AS -> HS: Registers itself with the home server
+  POST /register 
+  {
+   url: "https://someapp.com/matrix",
+   as_token: "T_a",
+   namespaces: {
+     users: [
+       {
+         "exclusive": true,
+         "regex": "@irc\.freenode\.net/.*"
+       }
+     ],
+     aliases: [
+       {
+         "exclusive": true,
+         "regex": "#irc\.freenode\.net/.*"
+       }
+     ]
+   }
+  }
+  
+  Returns 200 OK:
+  {
+    hs_token: "T_h"
+  }
+
+2. IRC user "Bob" says "hello?" on "#matrix" at timestamp 1421416883133:
+
+::  
+
+  - AS stores message as potential scrollback.
+  - Nothing happens as no Matrix users are in the room.
+ 
+3. Matrix user "@alice:hsdomain.com" wants to join "#matrix":
+
+::
+
+  User -> HS: Request to join "#irc.freenode.net/#matrix:hsdomain.com"
+  
+  HS -> AS: Room Query "#irc.freenode.net/#matrix:hsdomain.com"
+  GET /rooms/%23irc.freenode.net%2F%23matrix%3Ahsdomain.com?access_token=T_h
+  [Starts blocking]
+    AS -> HS: Creates room. Gets room ID "!aasaasasa:hsdomain.com".
+    AS -> HS: Sets room name to "#matrix".
+    AS -> HS: Sends message as ""@irc.freenode.net/Bob:hsdomain.com"
+      PUT /rooms/%21aasaasasa%3Ahsdomain.com/send/m.room.message
+                      ?access_token=T_a
+                      &user_id=%40irc.freenode.net%2FBob%3Ahsdomain.com
+                      &ts=1421416883133
+      {
+        body: "hello?"
+        msgtype: "m.text"
+      }
+    HS -> AS: User Query "@irc.freenode.net/Bob:hsdomain.com"
+      GET /users/%40irc.freenode.net%2FBob%3Ahsdomain.com?access_token=T_h
+      [Starts blocking]
+        AS -> HS: Creates user using CS API extension.
+          POST /register?access_token=T_a
+          {
+            type: "m.login.application_service",
+            user: "irc.freenode.net/Bob"
+          }
+        AS -> HS: Set user display name to "Bob".
+      [Finishes blocking]
+  [Finished blocking]
+  
+  - HS sends room information back to client.
+  
+4. @alice:hsdomain.com says "hi!" in this room:
+
+::
+
+  User -> HS: Send message "hi!" in room !aasaasasa:hsdomain.com
+  
+  - HS sends message.
+  - HS sees the room ID is in the AS namespace and pushes it to the AS.
+    
+  HS -> AS: Push event
+  PUT /transactions/1?access_token=T_h
+  {
+    events: [
+      {
+        content: {
+          body: "hi!",
+          msgtype: "m.text"
+        },
+        origin_server_ts: <generated by hs>,
+        user_id: "@alice:hsdomain.com",
+        room_id: "!aasaasasa:hsdomain.com",
+        type: "m.room.message"
+      }
+    ]
+  }
+  
+  - AS passes this through to IRC.
+  
+ 
+5. IRC user "Bob" says "what's up?" on "#matrix" at timestamp 1421418084816:
+
+::
+
+  IRC -> AS: "what's up?"
+  AS -> HS: Send message via CS API extension
+  PUT /rooms/%21aasaasasa%3Ahsdomain.com/send/m.room.message
+                  ?access_token=T_a
+                  &user_id=%40irc.freenode.net%2FBob%3Ahsdomain.com
+                  &ts=1421418084816
+  {
+    body: "what's up?"
+    msgtype: "m.text"
+  }
+  
+  - HS modifies the user_id and origin_server_ts on the event and sends it.