finishe server-api server part

Author: veaba

README.md

@@ -10,7 +10,6 @@ gitbook 见 ：https://socket.gitbook.io/docs/
 > 剩下API 尚未完成
 
 ## 目录
-
 * [关于本socket.io中文文档](README.md)
 * [socke.IO website](https://socket.io/)
 
@@ -38,33 +37,34 @@ gitbook 见 ：https://socket.gitbook.io/docs/
         * [2.1.10 广播消息](docs/overview/broadcasting_messages.md)   
         * [2.1.111 作为跨浏览器使用websocket](docs/overview/using_it_just_as_a_cross_browser_websocket.md)     
 
-    * [2.2 房间和命名空间]() todo
+    * [2.2 房间和命名空间]()
         * [2.2.1 命名空间](docs/rooms_and_namespaces/namespaces.md)
         * [2.2.2 房间](docs/rooms_and_namespaces/rooms.md)
         * [2.2.3 给外部发送消息](docs/rooms_and_namespaces/sending_message_from_the_outside-world.md)
 
-    * [2.3 migrating_from_0.9]()
-        * [2.3.1 authentication_differences](docs/migrating_from_0.9/authentication_differences.md )
-        * [2.3.2 parser_protocol_differences](docs/migrating_from_0.9/parser_protocol_differences.md)
-        * [2.3.3 log_differences](docs/migrating_from_0.9/log_differences.md)
-        * [2.3.4 shorcuts](docs/migrating_from_0.9/shorcuts.md)
-
-    * [2.4 using_multiple_nodes]()
-        * [2.4.1 apache_httpd_configuration](docs/using_multiple_nodes/apache_httpd_configuration.md)
-        * [2.4.2 passing_events_between_nodes](docs/using_multiple_nodes/passing_events_between_nodes.md)
-        * [2.4.3 haproxy_configuration](docs/using_multiple_nodes/haproxy_configuration.md)
-        * [2.4.4 sticky_load_balancing](docs/using_multiple_nodes/sticky_load_balancing.md)
-        * [2.4.5 nginx_configuration](docs/using_multiple_nodes/nginx_configuration.md)
-        * [2.4.6 using_node.js_cluster](docs/using_multiple_nodes/using_node.js_cluster.md)
-
-    * [2.5 logging_and_debugging]()
-        * [2.5.1 available_debugging_scopes](docs/logging_and_debugging/available_debugging_scopes.md)
-
-    * [2.6 emit_cheatsheet](docs/emit_cheatsheet.md)
-
-    * [2.7 internals_overview]()
-        * [2.7.1 internals_overview_dependency_graph_under_the_hood](docs/internals_overview_dependency_graph_under_the_hood.md)
-        * [2.7.2 internals_overview_dependency_graph](docs/internals_overview_dependency_graph.md)
+    * [2.3 从0.9迁移版本 migrating_from_0.9]()
+        * [2.3.1 身份验证差异](docs/migrating_from_0.9/authentication_differences.md )
+        * [2.3.2 日志差异](docs/migrating_from_0.9/log_differences.md)
+        * [2.3.3 快捷方式](docs/migrating_from_0.9/shorcuts.md)
+        * [2.3.4 配置差异](docs/migrating_from_0.9/configuration_differences.md)
+        * [2.3.5 解析器/协议差异](docs/migrating_from_0.9/parser_protocol_differences.md)
+
+    * [2.4 多路节点使用]()
+        * [2.4.1 Apache httpd配置](docs/using_multiple_nodes/apache_httpd_configuration.md)
+        * [2.4.2 在节点之间传递事件](docs/using_multiple_nodes/passing_events_between_nodes.md)
+        * [2.4.3 Haproxy配置](docs/using_multiple_nodes/haproxy_configuration.md)
+        * [2.4.4 粘性负载均衡](docs/using_multiple_nodes/sticky_load_balancing.md)
+        * [2.4.5 Nginx配置](docs/using_multiple_nodes/nginx_configuration.md)
+        * [2.4.6 使用node.js集群](docs/using_multiple_nodes/using_node.js_cluster.md)
+
+    * [2.5 日志和调试]()
+        * [2.5.1 可用的调试范围](docs/logging_and_debugging/available_debugging_scopes.md)
+
+    * [2.6 emit 备忘单](docs/emit_cheatsheet.md)
+
+    * [2.7 内部概述]()
+        * [2.7.1 内部概述引擎底层依赖关系图](docs/internals_overview_dependency_graph_under_the_hood.md)
+        * [2.7.2 内部概述关系图](docs/internals_overview_dependency_graph.md)
 
     * [2.8 faq](docs/faq.md)   
 

SUMMARY.md

@@ -51,9 +51,9 @@
 
     * [2.6 emit 备忘单](docs/emit_cheatsheet.md)
 
-    * [2.7 internals_overview]()
-        * [2.7.1 internals_overview_dependency_graph_under_the_hood](docs/internals_overview_dependency_graph_under_the_hood.md)
-        * [2.7.2 internals_overview_dependency_graph](docs/internals_overview_dependency_graph.md)
+    * [2.7 内部概述]()
+        * [2.7.1 内部概述引擎底层依赖关系图](docs/internals_overview_dependency_graph_under_the_hood.md)
+        * [2.7.2 内部概述关系图](docs/internals_overview_dependency_graph.md)
 
     * [2.8 faq](docs/faq.md)   
 
@@ -120,38 +120,40 @@
 * [4 服务端-API(Server-API)]()
 
     * [4.1 server]()
-        * [4.1.1 new_server_httpserver_options](server-api/server/new_server_httpserver_options.md)
-        * [4.1.2 new_server_port_options](server-api/server/new_server_port_options.md)
-        * [4.1.3 new_server_options](server-api/server/new_server_options.md)
-        * [4.1.4 server_sockets](server-api/server/server_sockets.md)
-        * [4.1.5 server_serverClient_value](server-api/server/server_serverClient_value.md)
-        * [4.1.6 server_path_value](server-api/server/server_path_value.md)
-        * [4.1.7 server_adapter_value](server-api/server/server_adapter_value.md)
-        * [4.1.8 server_origins_value](server-api/server/server_origins_value.md)
-        * [4.1.9 server_origins_fn](server-api/server/server_origins_fn.md)
-        * [4.1.10 server_attach_port_options](server-api/server/server_attach_port_options.md)
-        * [4.1.11 server_listen_httpServer_options](server-api/server/server_listen_httpServer_options.md)
-        * [4.1.12 server_listent_port_options](server-api/server/server_listent_port_options.md)
-        * [4.1.13 server_bind_engine](server-api/server/server_bind_engine.md)
-        * [4.1.14 server_onconnection_socket](server-api/server/server_onconnection_socket.md)
-        * [4.1.15 server_of_nsp](server-api/server/server_of_nsp.md)
-        * [4.1.16 server_close_callback](server-api/server/server_close_callback.md)
-        * [4.1.17 server_engine_generateid](server-api/server/server_engine_generateid.md)
+        * [4.1.1 HTTP服务选项 new_server_httpserver_options](server-api/server/new_server_httpserver_options.md)
+        * [4.1.2 服务器端口选项 new_server_port_options](server-api/server/new_server_port_options.md)
+        * [4.1.3 服务器选项 new_server_options](server-api/server/new_server_options.md)
+        * [4.1.4 服务器sockets server_sockets](server-api/server/server_sockets.md)
+        * [4.1.5 服务器serverClient值 server_serverClient_value](server-api/server/server_serverClient_value.md)
+        * [4.1.6 服务器路径值 server_path_value](server-api/server/server_path_value.md)
+        * [4.1.7 服务器适配器值 server_adapter_value](server-api/server/server_adapter_value.md)
+        * [4.1.8 服务器源值 server_origins_value](server-api/server/server_origins_value.md)
+        * [4.1.9 服务器源函数 server_origins_fn](server-api/server/server_origins_fn.md)
+        * [4.1.10 服务器附加HTTP服务选项 server_attach_httpServer_options](server-api/server/server_attach_httpServer_options.md)
+        * [4.1.11 服务器附加端口选项 server_attach_port_options](server-api/server/server_attach_port_options.md)
+        * [4.1.12 服务器监听HTTP服务选项 server_listen_httpServer_options](server-api/server/server_listen_httpServer_options.md)
+        * [4.1.13 服务器监听端口选项 server_listent_port_options](server-api/server/server_listent_port_options.md)
+        * [4.1.14 服务器绑定引擎 server_bind_engine](server-api/server/server_bind_engine.md)
+        * [4.1.15 服务器连接socket server_onconnection_socket](server-api/server/server_onconnection_socket.md)
+        * [4.1.16 服务器命名空间(nsp) server_of_nsp](server-api/server/server_of_nsp.md)
+        * [4.1.17 服务器关闭回调 server_close_callback](server-api/server/server_close_callback.md)
+        * [4.1.18 服务器引擎生成socket ID server_engine_generateid](server-api/server/server_engine_generateid.md)
 
     * [4.2 namespace]()
-        * [4.2.1 namespace_name](server-api/namespace/namespace_name.md)
-        * [4.2.2 namespace_connectid](server-api/namespace/namespace_connectid.md)
-        * [4.2.3 namespace_adapter](server-api/namespace/namespace_adapter.md)
-        * [4.2.4 namespace_to_room](server-api/namespace/namespace_to_room.md)
-        * [4.2.4 namespace_in_room](server-api/namespace/namespace_in_room.md)
-        * [4.2.5 namespace_emit_eventname_args](server-api/namespace/namespace_emit_eventname_args.md)
-        * [4.2.6 namespace_clients_callback](server-api/namespace/namespace_clients_callback.md)
-        * [4.2.7 namespace_use_fn](server-api/namespace/namespace_use_fn.md)
-        * [4.2.8 event_connect](server-api/namespace/event_connect.md)
-        * [4.2.9 event_connection](server-api/namespace/event_connection.md)
-        * [4.2.10 flag_volatile](server-api/namespace/flag_volatile.md)
-        * [4.2.11 flag_binary](server-api/namespace/flag_binary.md)
-        * [4.2.12 flag_local](server-api/namespace/flag_local.md)
+        * [4.2.1 namespace](server-api/namespace/namespace.md)
+        * [4.2.2 namespace_name](server-api/namespace/namespace_name.md)
+        * [4.2.3 namespace_connected](server-api/namespace/namespace_connected.md)
+        * [4.2.4 namespace_adapter](server-api/namespace/namespace_adapter.md)
+        * [4.2.5 namespace_to_room](server-api/namespace/namespace_to_room.md)
+        * [4.2.6 namespace_in_room](server-api/namespace/namespace_in_room.md)
+        * [4.2.7 namespace_emit_eventname_args](server-api/namespace/namespace_emit_eventname_args.md)
+        * [4.2.8 namespace_clients_callback](server-api/namespace/namespace_clients_callback.md)
+        * [4.2.9 namespace_use_fn](server-api/namespace/namespace_use_fn.md)
+        * [4.2.10 event_connect](server-api/namespace/event_connect.md)
+        * [4.2.11 event_connection](server-api/namespace/event_connection.md)
+        * [4.2.12 flag_volatile](server-api/namespace/flag_volatile.md)
+        * [4.2.13 flag_binary](server-api/namespace/flag_binary.md)
+        * [4.2.14 flag_local](server-api/namespace/flag_local.md)
 
     * [4.3 socket]()
         * [4.3.1 socket_id](server-api/socket/socket_id.md)

server-api/namespace/event_connect.md

@@ -0,0 +1,15 @@
+## Event:'connect'
+
+- `socket` (Socket) 与 客户端的socket 连接
+
+在来自客户端的连接上激发。
+
+```js
+io.on('connect',socket=>{
+    // ...
+})
+
+io.of('/admin').on('connect',socket=>{
+    // ... 
+})
+```

server-api/namespace/event_connection.md

@@ -0,0 +1,4 @@
+## Event:'connection' 
+
+同 [Event:'connect'](https://socket.io/docs/server-api/#Event-%E2%80%98connect%E2%80%99)
+

server-api/namespace/flag_binary.md

@@ -0,0 +1,9 @@
+## Flag:'binary'
+
+(二进制传输可以提高性能)
+
+指定发出的数据中是否存在二进制数据。指定时提高性能。可以是 `true` 或者 `false`
+
+```js
+io.binary(false).emit('an event',{some:'data'});
+```

server-api/namespace/flag_local.md

@@ -0,0 +1,8 @@
+## Flag:'local'
+
+后续事件发出设置一个修饰符，该修饰符表示事件数据将仅广播到当前节点（使用redis适配器时）。
+
+
+```js
+io.local.emit('an event',{some:'data'});
+```

server-api/namespace/flag_volatile.md

@@ -0,0 +1,7 @@
+## Flag:'volatile'
+
+为后续事件发出设置一个修饰符，如果客户端没有准备好接收消息（由于网络缓慢或其他问题，或者由于它们通过长轮询连接并且处于请求响应周期的中间），则事件数据可能会丢失。
+
+```js
+io.volatile.emit('an event',{some:'data'}) // 客户可能会收到，也可能不会收到。
+```

server-api/namespace/namespace.md

@@ -0,0 +1,8 @@
+## 命名空间 
+
+表示在由路径名标识的给定作用域下连接的套接字池（例如：`/chat`）。
+
+客户端总是连接到`/`（主命名空间），然后可能连接到其他命名空间（同时使用相同的基础连接）。
+
+关于如何以及为什么，请看一下：[房间(room)和名称空间(Namespace)](https://socket.io/docs/rooms-and-namespaces/)。
+

server-api/namespace/namespace_adapter.md

@@ -0,0 +1,7 @@
+## namespace.adapter
+
+- (Adapter)
+
+用于命名空间的适配器。当使用基于redis的适配器时很有用，因为它公开了跨集群管理套接字和房间的方法。
+
+**注意**：主命名空间的适配器可以使用`io.of('/').adapter`访问。

server-api/namespace/namespace_clients_callback.md

@@ -0,0 +1,31 @@
+## namespace.clients(callback)
+
+- `callback` (Function)
+
+取连接到此命名空间的客户端ID列表（如果适用，跨所有节点）。
+
+```js
+const io =require('socket.io')();
+io.of('/chat'),clients((error,clients)=>{
+    if (error) throw error;
+    console.log(clients) // => [PZDoMHjiu8PYfRiKAAAF, Anw2LatarvGVVXEIAAAD]
+})
+```
+
+获取命名空间房间中所有客户端的示例：
+
+```js
+io.of('/chat').in('general').clients((error,clients)=>{
+    if(error) throw error;
+    console.log(clients)// [Anw2LatarvGVVXEIAAAD]
+})
+```
+
+与广播一样，默认值是来自默认命名空间 `/` 的所有客户端：
+
+```js
+io.clients((error,clients)=>{
+    if(error) throw error;
+    console.log(clients); // [6em3d4TJP8Et9EMNAAAA, G5p55dHhGgUnLUctAAAB]
+})
+```

server-api/namespace/namespace_connected.md

@@ -0,0 +1,6 @@
+## namespace.connected
+
+- (Object)
+
+连接到此命名空间并按`id`索引的`Scoket`对象的哈希。
+

server-api/namespace/namespace_connectid.md

@@ -0,0 +1,20 @@
+## namespace.emit(eventName[, …args])
+
+- `eventName` (String)
+- `args`
+
+向所有连接的客户端emit事件,以下方法两个是等同的：
+
+```js
+
+const io= require('socket.io')();
+io.emit('an event send to all connected clients'); //主命名空间
+
+const chat = io.of('/chat');
+chat.emit('an event send to all connected clients in chat namespace');
+```
+
+**注意**:从命名空间发出时不支持确认。
+
+
+

server-api/namespace/namespace_emit_eventname_args.md

@@ -0,0 +1,3 @@
+## namespace.in(root)
+
+同 [namespace.to(room)](https://socket.io/docs/server-api/#namespace-to-room)

server-api/namespace/namespace_in_room.md

@@ -0,0 +1,5 @@
+## namespace.name
+
+- (String)
+
+命名空间标识符属性。

server-api/namespace/namespace_name.md

@@ -0,0 +1,15 @@
+## namespace.to(room)
+
+- `room` (String)
+- **Returns** `Namespace` 用于连接
+
+为后续事件发射设置一个修饰符，该事件将仅广播给已加入指定的`room`客户端。
+
+要emit到多个房间，可以多次调用。
+
+```js
+const io = require('socket.io')();
+const adminNamespace=io.of('/admin');
+
+adminNamespace.to('level1').emit('an event',{some:"data"});
+```

server-api/namespace/namespace_to_room.md

@@ -0,0 +1,15 @@
+## namespace.use(fn)
+
+- `fn` (Function)
+
+注册一个中间件，它是一个为每个传入Socket 执行的函数，并作为参数接收socket和一个函数，以选择将执行推迟到下一个注册的中间件。
+
+传递到中间件回调的错误作为特殊错误包发送到客户端。
+
+```js
+io.use((socket,next)=>{
+    if (socket.request.header.cookie) return next();
+    next(new Error('authentication error'));
+})
+
+```

server-api/namespace/namespace_use_fn.md

@@ -0,0 +1,68 @@
+## Server
+
+暴露 `require('socket.io')`
+
+### new Server(httpServer[,options])
+
+- `httpServer` (http.server) 要绑定到服务器
+- `options` (Object)
+
+新旧比较：
+
+```js
+const io = require('socket.io')()
+
+// 或者
+const Server=require('socket.io');
+const io= new Server()
+
+```
+
+可用选项：
+
+| 选项 | 默认值 | 描述 |
+|------|------- |------|
+|`path`|`/socket.io`|要捕获的路径名称|
+|`serverClinet`|`true`|是否提供客户端文件|
+|`adapter`|-|要使用的适配器。默认为socket.io随附的基于内存的`Adapter`实例。见[socket.io-adapter](https://github.com/socketio/socket.io-adapter)|
+|`origins`|`*`|允许源|
+|`parser`|-|要使用的分析器。默认为socket.io附带的分析器实例,见[ socket.io-parser](https://github.com/socketio/socket.io-parser)|
+||||
+
+基础engine.io服务器的可用选项：
+
+| 选项 | 默认值 | 描述 |
+|------|------- |------|
+|`pingTimeout`|`5000`|多少毫秒没有pong包则认为连接已关闭|
+|`pingInterval`|`25000`|发送新的ping数据包前需要多少毫秒|
+|`upgradeTimeout`|`10000`|取消未完成的传输升级之前需要多少毫秒|
+|`maxHttpBufferSize`|`10e7`|在关闭会话之前（为了避免DOS），一条消息可以有多少字节或字符。|
+|`allowRequest`||一个函数，接收给定的握手或升级请求作为其第一个参数，并决定是否继续。第二个参数是一个需要用决定的信息调用的函数：`fn(err，success)`，其中`success`是一个布尔值，false表示请求被拒绝，err是一个错误代码。|
+|`transports`|`['polling','websocket']`|传输以允许连接到|
+|`allowUpgraders`|`true`|是否允许传输升级|
+|`preMessageDeflate`|`true`|websocket permessage deflate扩展的参数（请参阅[ws 模块](https://github.com/einaros/ws) API文档）。设置`false`为禁用|
+|`httpCompress`|`true`|轮询传输的HTTP压缩参数（请参阅[zlib](http://nodejs.org/api/zlib.html#zlib_options) API文档）,设置`false`为禁用。|
+|`cookie`|`io`|包含要作为握手响应头一部分发送的客户端SID的HTTP cookie的名称。设置为`false`不发送。|
+|`cookiePath`|`/`|上述`cookie`选项的路径。如果为false，则不会发送路径，这意味着浏览器将只在engine.io附加路径（`/engine.io`）上发送cookie。设置为“假”不在所有请求上保存IO cookie。|
+|`cookieHttpOnly`|`true`|如果客户端API（如javascript）无法访问`true` httponly IO cookie。如果`cookie`或`cookiepath`,设置为false，则此选项无效。|
+|`wsEngine`|`ws`|要使用的WebSocket服务器实现。指定的模块必须符合WS接口（请参阅[ws模块](https://github.com/websockets/ws/blob/master/doc/ws.md)API文档）。默认值为`ws`。另外一个可选的C++插件也可以安装`uws`模块。|
+||||
+
+在这些选项中：
+
+- `pingTimeout`和`pingInterval`参数将影响客户机知道服务器不再可用之前的延迟。例如，如果底层TCP连接由于网络问题而未正确关闭，则客户端可能需要等待`pingTimeout+pingInterval` 毫秒，然后才能获得`disconect`(断开连接)事件。
+
+- `transports`数组的顺序很重要。默认情况下，首先建立一个长轮询连接，然后在可能的情况下升级到WebSocket。使用`['websocket']`意味着如果无法打开websocket连接，就不会有回退。
+
+```js
+const server= require('http').createServerr()
+
+const io = require('socket.io')(server,{
+    path:'/test',
+    serverClient:false,
+    // 以下是Engine.io选项
+    pingInterval:10000,
+    pingTimeout:5000,
+    cookie:false
+})
+```