grappler

格鬥者

Grappler 是一個用於「comet」連線的簡約伺服器，它在所有傳輸中公開單一、一致的 API。 Grappler 目前支援以下傳輸（每種傳輸都有目前已知支援的瀏覽器清單）：

• WebSockets（具有 Flash 策略支援－監視與 grappler 伺服器相同連接埠上的政策請求）
  • Firefox 4、Chrome 4+、Safari 5 或任何至少支援 Flash 9.x 的瀏覽器
• XHR 多部分串流媒體
  • Firefox 3+、Safari 5（也許還有 4.0？）、Chrome 1+
• 伺服器發送的事件
  • Chrome 6+、Safari 5、Opera 9.x-10.x（僅限 DOM）
• XHR 長輪詢
  • 任何支援 XMLHttpRequest* 的瀏覽器

* - 某些瀏覽器的 XMLHttpRequest 實作包含意外的怪癖（例如 Android 1.6 的內建 Web 瀏覽器）

要求

• Node.JS（使用 v0.4.2 進行測試 - 可能適用於舊版）
• 支援上述傳輸之一的客戶端。
• 對於 HTTP（非 WebSocket）用戶端，只有當客戶端要向伺服器傳送訊息（即透過 POST）時，才必須啟用 cookie。

範例（廣播迴聲）

1. 運行examples/echo/server.js。
2. 在一個或多個瀏覽器中存取演示伺服器的頁面：http://127.0.0.1:8080/demo.htm

應用程式介面

Grappler 匯出一個主要物件： Server 。

lib/common.js 匯出LOG和STATE對象，其中包含分別用於記錄訊息和檢查客戶端狀態時的常數。

LOG物件是：

 {
  INFO: 1,
  WARN: 2,
  ERROR: 3
}

STATE物件是：

 {
  ACCEPTED: 1, // internal use only
  TEMP: 2, // internal use only
  PROTO_HTTP: 4, // client is HTTP-based
  PROTO_WEBSOCKET: 8 // client is WebSocket-based
}

伺服器

建構子： new Server([選項], [fnHandleNormalHTTP], [fnAcceptClient])

建立 grappler 伺服器的新實例。

options是一個具有以下預設值的物件：

 {
  // A callback for receiving "debug" information. It is called with two arguments: message and message level.
  // Message level is one of the values in the `LOG` object.
  logger: function(msg, msgLevel) {},

  // A string or array of strings which denote who is allowed to connect to this grappler Server instance.
  // The format of the string is: "hostname:port", "hostname", or an asterisk substituted for either the hostname
  // or port, or both, to act as a wildcard.
  origins: "*:*",
  
  // An integer value in milliseconds representing the interval in which a ping is sent to an HTTP client for those
  // transports that need to do so.
  pingInterval: 3000,

  // A storage provider used to store client objects. The default is to use 'object', a simple hash. Other available
  // storage providers can be found in lib/storage. The value here is the name without the 'storage' prefix and file extension.
  storage: 'object'
}

fnHandleNormalHTTP是回呼函數，能夠覆寫傳入 HTTP 連線的處理程序。如果沒有傳送標頭，則 grappler 會控制連線。提供給此回呼的參數與http.Server的request事件相同，即： http.ServerRequest 和 http.ServerResponse 物件。需要注意的是，如果您希望 grappler 自動處理所有傳入的 HTTP 連接，但希望為fnAcceptClient指定回調，則需要為fnHandleNormalHTTP指定false值。

fnAcceptClient是在客戶端連線時執行的回呼。此回呼的主要目的是有機會立即拒絕客戶端進一步存取 grappler 伺服器。例如，您的應用程式可能會維護一個黑名單，或者可能會在一定時間內進行 x 個連線後自動將某個 IP 列入黑名單/限制。如果此回呼傳回false ，連線將自動斷開，否則將允許連線。此回呼接收一個參數，該參數是表示連接的net.Stream物件。

事件：連接

function(client) { }

每次新客戶端成功連接到系統時都會發出此事件。 client是HttpClient的實例。

事件：錯誤

function(err) { }

發生意外錯誤時發出。

監聽（端口，[主機]）

啟動伺服器偵聽指定的port和host 。如果省略host ，伺服器將偵聽任何 IP 位址。

廣播（資料[，編碼]）

使用可選encoding將data傳送到每個連接的客戶端。

關閉（）

透過不再偵聽傳入連線並切斷任何現有客戶端連線來關閉伺服器。

Http客戶端

grappler 中也使用了另一個重要的對象，那就是HttpClient物件。 HttpClient代表連接到伺服器的用戶，可用於與該用戶互動。

事件：排水

function() { }

當客戶端的寫入緩衝區變空時發出。

事件：關閉

function() { }

當客戶端斷開連線時發出。

狀態

包含客戶端目前狀態的位元欄位。請參閱前面提到的STATE物件以了解有效位元。

遠端位址

客戶端的IP位址。

寫（資料[，編碼]）

使用可選encoding將data傳送到客戶端。如果整個資料已成功刷新到核心緩衝區，則此函數傳回true 。否則，如果全部或部分資料在使用者記憶體中排隊，它將傳回false 。當核心緩衝區再次空閒時，會發出排出drain 。

廣播（資料[，編碼]）

使用可選的encoding將data傳送到所有其他連接的客戶端。

斷開（）

強制切斷客戶端與伺服器的連線。