Basic HTTP Push Relay Protocol

英文原方：

https://pushmodule.slact.net/protocol.html

简单的HTTP推协议

1 介绍

   1.1目的   

   本协议的初衷是提供一种HTTP客户端透明长连接的支持，在服务端连接大部分时间都是空闲的，也不会被中继传递。   

 

   1.2 一般性的说明    

   略  

   1.3 术语

   本规范使用一系列的名词来指代协议中的碰到的对象。

    服务器（server）

         实现本协议的HTTP服务器。

    客户端（client）

        一个可以向HTTP服务器发起TCP/IP连接的程序。

      消息（message）

        特定应用的数据，通常包含在请求或者回复的主体中。

    信道（channel）

        代表某个传递消息的路径资源。每个信道有单独的消息队列。

     订阅者（subscriber）

        一个向服务器发出HTTP请求，希望在某个信道上接受消息的客户端。

    发布者（publisher）

        一个向服务器发出HTTP请求，希望将其信息通过信道发送到订阅者那里。

     信道标示（channel id）

        可以标示信道的一串特别的字符串。

    位置（location）

        服务器的一个URL。

2.需求

   2.1 服务器端的要求

    HTTP服务器必须可以通过URL来设定发布和订阅的位置。所有发到发布位置的请求都必须被认为是发布者的请求。所有发到订阅位置的请求都被认为是订阅者 的请求。

    服务器必须可以通过特定的字符来识别不同的信道。比如，可以是URL的一个参数（/foo/?id=123）或者是一个cookie。当然你也可以用其他 方法来区别信道，但是强烈不建议你这么做。

    服务器必须接收发到发布位置的请求并迅速回复。当然也必须接收发到订阅位置的请求，但不必马上回复。

   2.2 客户端的要求

    所有客户端必须产生有效的HTTP请求。订阅客户端（比如浏览器）必须有应对Last-Modified和Etag的缓存机制。  

   2.3 信道标示  

    服务端不负责产生信道，而应由客户端来产生。

3. 服务器的操作

   发布者的请求就像一个通知，通过某个信道把消息发到订阅者那里。订阅者的请求就是告知服务器客户端已经准备好接受消息了。

   3.1 订阅者     

    服务器必须接收所有发到发布位置的的HTTP GET请求。其他方法的HTTP请求应该回应405状态（Method Not Allowed）。

    订阅者的请求被认为是打算订阅消息的告知。订阅者可以请求已经存在、已经无效或者还没有有效的请求。订阅者通过If-Modified-Since和If -None-Match来区别这些消息。如果客户端没有If-Modified-Since头，则必须被认为假定他请求的是信道里最老的那条消息。每一个 200(OK)的回复消息必须包含有Last-Modified和Etag头，以便订阅者可以通过这些头来获取下一条消息。此外，200(ok)也必须包 含消息发布者的Content-Type头，除非发布者没有指定Content-Type或者服务器的配置刻意想隐藏Content-Type。

   

    HTTP服务器一般有多种推的机制。服务器针对订阅者的请求回应的行为应该是可配置的，而且必须是以下列出的机制：            

        长时间轮询（Long-Polling）

        针对已经存在的消息将迅速的回应；如果是还未有效的请求必须延迟直到消息变成有效。延迟的回复必须满足下面所有的条件：

        + 在消息有效时，包含消息及Content-Type的200(ok)回复必须立即发出。这个回复应该与那些马上回复的消息没有区别。

        + 如果订阅者等待的信道被删除了或者因为某种原因变得无效时，服务器端必须马上发出一个410(gone)的回复。

        + 如果另外一个订阅者的请求与该请求有冲突。服务器必须马上回应409（Conflict）。

        间隔轮询（Interval-Polling）

        所有的请求必须马上回应，如果还没有有效消息，服务器必须马上回应304（Not Modified）。

   

   另外，当服务器在同一个信道上接受了超过一个订阅者时，它必须有如下行为：

   广播（Broadcast）

        没有另外的行为。

    后进先出（Last-in, first-out）

        除了最近等待的那个订阅者，给其他的订阅者回应409（Conflict）。

    先进后出（First-in, last-out）

        除了等待最久的那个订阅者，给其他的订阅者回应409（Conflict）。

    

    服务器必须是可以配置这些行为的，而且默认是广播的。        

  3.2 发布者   

    服务器必须接受所有发到发布位置的有效的HTTP请求。针对发布者请求的不同服务器必须满足以下条件：

    * GET 请求：如果存在该信道机就回复200(OK)，否则回复404(Not Found )。

    * PUT 请求：直接回复200(OK)，如果该信道不存在就根据信道标示建立一个。

    * DELETE 请求：如果信道存在，回复200(OK)并删除该信道。该信道的所有订阅者会收到410（Gone）的回复。如果不存在，回复404（Not Found）。

    * POST请求是用来发送消息的。消息包含于请求的主体中，可以以任何一种编码通过信道发送。消息必须马上发送到那些长期等候的那些订阅者那里。另外，消息 可以保存下来，以便将来之用。最老的消息也可以被删除。对于POST请求，如果有向订阅者发出这个消息，服务器必须回应201（Created）。如果没 有，就回应202（Accepted）。Content-Type头必须跟随消息一起被转发。

    消息的保存极限参数应该是可配置的。发布者的位置应该可以配置的。所有给发布者200的回复必须包含该应用的信道信息。这些信息可能包含保存的消息数量和 长期等待的订阅者数量。针对这些信息，服务器或许可以实现某种协商。