# HG changeset patch
# User neko259 <neko259@gmail.com>
# Date 2015-05-20 14:32:32
# Node ID 762bb5078ec527226a73a8295e1225f4dbc581de
# Parent  d679decc9ebf2680b853778b8b8014632f62b15a

Moved the samples to the protocol document. Title the protocol "DIP" and
number its first document

diff --git a/docs/sync.markdown b/docs/dip-1.markdown
rename from docs/sync.markdown
rename to docs/dip-1.markdown
--- a/docs/sync.markdown
+++ b/docs/dip-1.markdown
@@ -1,10 +1,16 @@
+# 0 Title #
+
+DIP-1 Common protocol description
+
 # 1 Intro #
 
-This document describes the server sync protocol.
+This document describes the Data Interchange Protocol (DIP), designed to
+exchange filtered data that can be stored as a graph structure between
+network nodes.
 
 # 2 Purpose #
 
-This protocol will be used to share the models (currently imageboard posts)
+This protocol will be used to share the models (originally imageboard posts)
 across multiple servers. The main differnce of this protocol is that the node
 can specify what models it wants to get and from whom. The nodes can get
 models from a specific server, or from all except some specific servers. Also
@@ -14,7 +20,7 @@ the models can be filtered by timestamps
 
 The node requests other node's changes list since some time (since epoch if
 this is the start). The other node sends a list of post ids or posts in the
-XML or JSON format.
+XML format.
 
 Protocol version is the version of the sync api. Model version is the version
 of data models. If at least one of them is different, the sync cannot be
@@ -60,9 +66,119 @@ The server is required to return the sta
 "pull" request gets the desired model id list by the given filter (e.g. thread, tags,
 author)
 
+Sample request is as follows:
+
+<?xml version="1.1" encoding="UTF-8" ?>
+<request version="1.0" type="pull">
+    <model version="1.0" name="post">
+        <timestamp_from>0</timestamp_from>
+        <timestamp_to>0</timestamp_to>
+        <tags>
+            <tag>tag1</tag>
+        </tags>
+        <sender>
+            <allow>
+                <key>abcehy3h9t</key>
+                <key>ehoehyoe</key>
+            </allow>
+            <!-- There can be only allow block (all other are denied) or deny block (all other are allowed) -->
+        </sender>
+    </model>
+</request>
+
+Under the <model> tag there are filters. Filters for the "post" model can
+be found in DIP-2.
+
+Sample response:
+
+    <?xml version="1.1" encoding="UTF-8" ?>
+    <response>
+        <status>success</status>
+        <models>
+            <id key="id1" type="ecdsa" local-id="1" />
+            <id key="id1" type="ecdsa" local-id="2" />
+            <id key="id2" type="ecdsa" local-id="1" />
+            <id key="id2" type="ecdsa" local-id="5" />
+        </models>
+    </response>
+
 ### 3.1.2 get ###
 
-"get" gets models by id list
+"get" gets models by id list.
+
+Sample request:
+
+    <?xml version="1.1" encoding="UTF-8" ?>
+    <request version="1.0" type="get">
+        <model version="1.0" name="post">
+            <id key="id1" type="ecdsa" local-id="1" />
+            <id key="id1" type="ecdsa" local-id="2" />
+        </model>
+    </request>
+
+Id consists of a key, key type and local id. This key is used for signing and
+validating of data in the model content.
+
+Sample response:
+
+    <?xml version="1.1" encoding="UTF-8" ?>
+    <response>
+        <!--
+             Valid statuses are 'success' and 'error'.
+        -->
+        <status>success</status>
+        <models>
+            <model name="post">
+                <!--
+                    Content tag is the data that is signed by signatures and must
+                    not be changed for the post from other node.
+                -->
+                <content>
+                    <id key="id1" type="ecdsa" local-id="1" />
+                    <title>13</title>
+                    <text>Thirteen</text>
+                    <thread><id key="id1" type="ecdsa" local-id="2" /></thread>
+                    <pub-time>12</pub-time>
+                    <!--
+                        Images are saved as attachments and included in the
+                        signature.
+                    -->
+                    <attachments>
+                        <attachment mimetype="image/png" name="12345.png">
+                            TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0
+                            aGlzIHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1
+                            c3Qgb2YgdGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0
+                            aGUgY29udGludWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yga25vd2xlZGdl
+                            LCBleGNlZWRzIHRoZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4=
+                        </attachment>
+                    </attachments>
+                </content>
+                <!--
+                    There can be several signatures for one model. At least one
+                    signature must be made with the key used in global ID.
+                 -->
+                <signatures>
+                    <signature key="id1" type="ecdsa" value="dhefhtreh" />
+                    <signature key="id45" type="ecdsa" value="dsgfgdhefhtreh" />
+                </signatures>
+            </model>
+            <model name="post">
+                <content>
+                    <id key="id1" type="ecdsa" local-id="id2" />
+                    <title>13</title>
+                    <text>Thirteen</text>
+                    <pub-time>12</pub-time>
+                    <edit-time>13</edit-time>
+                    <tags>
+                        <tag>tag1</tag>
+                    </tags>
+                </content>
+                <signatures>
+                    <signature key="id2" type="ecdsa" value="dehdfh" />
+                </signatures>
+            </model>
+        </models>
+    </response>
 
 ### 3.1.3 put ###
 
@@ -78,7 +194,7 @@ across the pool.
 If the request if completely not supported, a "not supported" status will be
 returned.
 
-### 3.2.2 "success"" ###
+### 3.2.2 "success" ###
 
 "success" status means the request was processed and the result is returned.
 
diff --git a/docs/samples/request_get.xml b/docs/samples/request_get.xml
deleted file mode 100644
--- a/docs/samples/request_get.xml
+++ /dev/null
@@ -1,7 +0,0 @@
-<?xml version="1.1" encoding="UTF-8" ?>
-<request version="1.0" type="get">
-    <model version="1.0" name="post">
-        <id key="id1" type="ecdsa" local-id="1" />
-        <id key="id1" type="ecdsa" local-id="2" />
-    </model>
-</request>
diff --git a/docs/samples/request_pull.xml b/docs/samples/request_pull.xml
deleted file mode 100644
--- a/docs/samples/request_pull.xml
+++ /dev/null
@@ -1,17 +0,0 @@
-<?xml version="1.1" encoding="UTF-8" ?>
-<request version="1.0" type="pull">
-    <model version="1.0" name="post">
-        <timestamp_from>0</timestamp_from>
-        <timestamp_to>0</timestamp_to>
-        <tags>
-            <tag>tag1</tag>
-        </tags>
-        <sender>
-            <allow>
-                <key>abcehy3h9t</key>
-                <key>ehoehyoe</key>
-            </allow>
-            <!-- There can be only allow block (all other are denied) or deny block (all other are allowed) -->
-        </sender>
-    </model>
-</request>
diff --git a/docs/samples/response_get.xml b/docs/samples/response_get.xml
deleted file mode 100644
--- a/docs/samples/response_get.xml
+++ /dev/null
@@ -1,58 +0,0 @@
-<?xml version="1.1" encoding="UTF-8" ?>
-<response>
-    <!--
-         Valid statuses are 'success' and 'error'.
-    -->
-    <status>success</status>
-    <models>
-        <model name="post">
-            <!--
-                Content tag is the data that is signed by signatures and must
-                not be changed for the post from other node.
-            -->
-            <content>
-                <id key="id1" type="ecdsa" local-id="1" />
-                <title>13</title>
-                <text>Thirteen</text>
-                <thread><id key="id1" type="ecdsa" local-id="2" /></thread>
-                <pub-time>12</pub-time>
-                <!--
-                    Images are saved as attachments and included in the
-                    signature.
-                -->
-                <attachments>
-                    <attachment mimetype="image/png" name="12345.png">
-                        TWFuIGlzIGRpc3Rpbmd1aXNoZWQsIG5vdCBvbmx5IGJ5IGhpcyByZWFzb24sIGJ1dCBieSB0
-                        aGlzIHNpbmd1bGFyIHBhc3Npb24gZnJvbSBvdGhlciBhbmltYWxzLCB3aGljaCBpcyBhIGx1
-                        c3Qgb2YgdGhlIG1pbmQsIHRoYXQgYnkgYSBwZXJzZXZlcmFuY2Ugb2YgZGVsaWdodCBpbiB0
-                        aGUgY29udGludWVkIGFuZCBpbmRlZmF0aWdhYmxlIGdlbmVyYXRpb24gb2Yga25vd2xlZGdl
-                        LCBleGNlZWRzIHRoZSBzaG9ydCB2ZWhlbWVuY2Ugb2YgYW55IGNhcm5hbCBwbGVhc3VyZS4=
-                    </attachment>
-                </attachments>
-            </content>
-            <!--
-                There can be several signatures for one model. At least one
-                signature must be made with the key used in global ID.
-             -->
-            <signatures>
-                <signature key="id1" type="ecdsa" value="dhefhtreh" />
-                <signature key="id45" type="ecdsa" value="dsgfgdhefhtreh" />
-            </signatures>
-        </model>
-        <model name="post">
-            <content>
-                <id key="id1" type="ecdsa" local-id="id2" />
-                <title>13</title>
-                <text>Thirteen</text>
-                <pub-time>12</pub-time>
-                <edit-time>13</edit-time>
-                <tags>
-                    <tag>tag1</tag>
-                </tags>
-            </content>
-            <signatures>
-                <signature key="id2" type="ecdsa" value="dehdfh" />
-            </signatures>
-        </model>
-    </models>
-</response>
diff --git a/docs/samples/response_pull.xml b/docs/samples/response_pull.xml
deleted file mode 100644
--- a/docs/samples/response_pull.xml
+++ /dev/null
@@ -1,10 +0,0 @@
-<?xml version="1.1" encoding="UTF-8" ?>
-<response>
-    <status>success</status>
-    <models>
-        <id key="id1" type="ecdsa" local-id="1" />
-        <id key="id1" type="ecdsa" local-id="2" />
-        <id key="id2" type="ecdsa" local-id="1" />
-        <id key="id2" type="ecdsa" local-id="5" />
-    </models>
-</response>
diff --git a/docs/samples/response_versionmismatch.xml b/docs/samples/response_versionmismatch.xml
deleted file mode 100644
--- a/docs/samples/response_versionmismatch.xml
+++ /dev/null
@@ -1,11 +0,0 @@
-<?xml version="1.1" encoding="UTF-8" ?>
-<response>
-    <status>error</status>
-    <!--
-         The detail field reply cases are limited. They are optional to
-         check, so the implementation can check the status, see 'error' and
-         just drop the response and not check the details. This is the main
-         reason detail was split to another field.
-    -->
-    <status-detail>protocol version mismatch</status-detail>
-</response>