Finished 'src/appendix/ap02-a_socket_application.md'.

Author: gnu4cn

projects/appendix/_build/default/lib/.rebar3/rebar_compiler_erl/source_project_apps.dag

@@ -5,5 +5,5 @@
               {applications,[kernel,stdlib]},
               {mod,{math_server_app,[]}},
               {env,[]},
-              {modules,[lib_chan,lib_chan_cs,lib_chan_mm,math_server,
-                        math_server_app,mod_math]}]}.
+              {modules,[lib_chan,lib_chan_auth,lib_chan_cs,lib_chan_mm,
+                        lib_md5,math_server,math_server_app,mod_math]}]}.

projects/appendix/_build/default/lib/math_server/ebin/lib_chan_auth.beam

@@ -0,0 +1,33 @@
+%% ---
+%%  Excerpted from "Programming Erlang, Second Edition",
+%%  published by The Pragmatic Bookshelf.
+%%  Copyrights apply to this code. It may not be used to create training material, 
+%%  courses, books, articles, and the like. Contact us if you are in doubt.
+%%  We make no guarantees that this code is fit for any purpose. 
+%%  Visit http://www.pragmaticprogrammer.com/titles/jaerlang2 for more book information.
+%%---
+-module(lib_chan_auth).
+-export([make_challenge/0, make_response/2, is_response_correct/3]).
+
+make_challenge() ->
+    random_string(25).
+make_response(Challenge, Secret) ->
+    lib_md5:string(Challenge ++ Secret).
+is_response_correct(Challenge, Response, Secret) ->
+    case lib_md5:string(Challenge ++ Secret) of
+	Response -> true;
+	_        -> false
+    end.
+
+%% random_string(N) -> a random string with N characters.
+random_string(N) -> random_seed(), random_string(N, []).
+random_string(0, D) -> D;
+random_string(N, D) ->
+    random_string(N-1, [random:uniform(26)-1+$a|D]).
+random_seed() ->
+    {_,_,X} = erlang:now(),
+    {H,M,S} = time(),
+    H1 = H * X rem 32767,
+    M1 = M * X rem 32767,
+    S1 = S * X rem 32767,
+    put(random_seed, {H1,M1,S1}).

projects/appendix/_build/default/lib/math_server/ebin/lib_md5.beam

@@ -0,0 +1,79 @@
+%% ---
+%%  Excerpted from "Programming Erlang, Second Edition",
+%%  published by The Pragmatic Bookshelf.
+%%  Copyrights apply to this code. It may not be used to create training material, 
+%%  courses, books, articles, and the like. Contact us if you are in doubt.
+%%  We make no guarantees that this code is fit for any purpose. 
+%%  Visit http://www.pragmaticprogrammer.com/titles/jaerlang2 for more book information.
+%%---
+-module(lib_md5).
+
+%% modfied to use BIFs
+
+-export([string/1, file/1, bin/1, binAsBin/1, digest2str/1]).
+
+-define(BLOCKSIZE, 32768).
+-define(IN(X,Min,Max), X >= Min, X =< Max).
+
+%% md5:string(string())      -> BinDigest
+%% md5:file(FileName)        -> {ok, BinDigest} | {error, E} 
+%% md5:digest2str(BinDigest) -> StringDigest
+
+%% md5:file works with chunks so should work correctly with extremely
+%% large files
+
+string(Str) -> digest2str(erlang:md5(Str)).
+
+file(File) ->
+    case file:open(File, [binary,raw,read]) of
+	{ok, P} -> loop(P, erlang:md5_init());
+	Error   -> Error
+    end.
+
+loop(P, C) ->
+    case file:read(P, ?BLOCKSIZE) of
+	{ok, Bin} ->
+	    loop(P, erlang:md5_update(C, Bin));
+	eof ->
+	    file:close(P),
+	    {ok, erlang:md5_final(C)}
+    end.
+
+digest2str(Digest) -> bin2str(binary_to_list(Digest)).
+
+bin2str([H|T]) ->
+    {H1, H2} = byte2hex(H),
+    [H1,H2|bin2str(T)];
+bin2str([]) ->
+    [].
+
+byte2hex(X) -> 
+    {nibble2hex(X bsr 4), nibble2hex(X band 15)}.
+
+nibble2hex(X) when ?IN(X, 0, 9)   -> X + $0;
+nibble2hex(X) when ?IN(X, 10, 15) -> X - 10 + $a.
+
+%% compute the md5 checksum of a binary
+bin(Bin) ->
+    C1 = erlang:md5_init(),
+    C2 = erlang:md5_update(C1, Bin),
+    C3 = erlang:md5_final(C2),
+    digest2str(C3).
+
+binAsBin(Bin) ->
+    C1 = erlang:md5_init(),
+    C2 = erlang:md5_update(C1, Bin),
+    erlang:md5_final(C2).
+
+    
+
+
+
+
+
+
+
+
+
+
+

projects/appendix/_build/default/lib/math_server/ebin/math_server.app

@@ -109,10 +109,192 @@ true
 > 然后即可执行命令 `erl -boot start_sasl -config elog4 -smp +S 12 -pa _build/default/lib/math_server/ebin` 启动 Erlang shell，并在其下执行上面的命令。
 
 
+### 透过网络访问服务器
 
 
+我们可以一台机器上，测试此代码。
 
 
+```erlang
+2> {ok, S} = lib_chan:connect("localhost",2233,math,"qwerty",{yes,go}).
+{ok,<0.100.0>}
+mod_math: run starting
+ArgC = {yes,go} ArgS = []
+3> lib_chan:rpc(S, {factorial,20}).
+2432902008176640000
+4> lib_chan:rpc(S, {fibonacci,15}).
+610
+5> lib_chan:disconnect(S).
+close
+mod_math stopping
+```
+
+## `lib_chan` 工作原理
+
+
+`lib_chan` 是使用四个模组中的代码构建的。
+
+- `lib_chan` 充当 “主模组”。程序员需要了解的例程，仅限 `lib_chan` 中导出那些。其他三个模组（将在下文讨论）在 `lib_chan` 实现内部用到；
+- `lib_chan_mm` 会编码及解码 Erlang 消息，并管理套接字通信；
+- `lib_chan_cs` 会建立该服务器，并管理客户端连接。他的主要任务之一，是限制客户端同时连接的最大数量；
+- `lib_chan_auth` 包含着简单挑战/响应式验证的代码。
 
 
+### `lib_chan`
+
+
+`lib_chan` 有着如下结构：
+
+
+```erlang
+-module(lib_chan).
+
+
+start_server(ConfigFile) ->
+    %% read configuration file - check syntax
+    %% call start_port_server(Port, ConfigData)
+    %% where Port is the required Port and ConfigData
+    %% contains the configuration data
+
+start_port_server(Port, ConfigData) ->
+    lib_chan_cs:start_raw_server(Port,
+				fun(Socket) ->
+					start_port_instance(Socket, ConfigData) end,
+    %% lib_chan_cs manages the connection
+    %% when a new connection comes the fun which is an
+    %% argument to start_raw_server will be called
+
+
+start_port_instance(Socket, ConfigData) ->
+    %% this is spawned when the client connects
+    %% to the server. Here we setup a middle man,
+    %% then perform authentication. If everything works call
+    %% really_start(MM, ArgC, {Mod, Func, ArgS})
+    %% (the last three arguments come from the configuration file
+
+
+really_start(MM, ArgC, {Mod, Func, ArgS}) ->
+    apply(Mod, Func, [MM, ArgC, ArgS]).
+
+
+connect(Host, Port, Service, Secret, ArgC) ->
+    %% client side code
+```
+
 ### `lib_chan_mm`：中间人
+
+`lib_chan_mm` 实现了一个中间人。他对应用隐藏了套接字通信，将 TCP 套接字上的数据流转换成 Erlang 消息。中间人负责组装消息（其可能已被分片），以及将 Erlang 项编码和解码为可在套接字上发送和接收的字节流。
+
+
+![中间人下的套接字通信](../images/lib_chan_mm.png)
+
+<a name="fig-8"></a>
+**图 8** -- **中间人下的套接字通信**
+
+
+现在快速浏览一下 [图 8，*中间人下的套接字通信](#fig-8) 的好时机，其展示了我们的中间人架构。当机器 `M1` 上的某个进程 `P1` 想要发送一条消息 `T` 到机器 `M2` 上的进程 `P2`时，他会执行 `MM1 ！{send, T}`。`MM1` 充当 `P2` 的 *代理*。发送到 `MM1` 的任何消息，都会被编码并写入套接字，并被发送到 `MM2`。`MM2` 会解码他在套接字上接收到的任何东西，并将消息 `{chan, MM2, T}` 发送给 `P2`。
+
+
+在机器 `M1` 上，进程 `MM1` 充当了 `P2` 的代理，而在 `M2` 上，进程 `MM2` 则会充当 `P1` 的代理。
+
+`MM1` 和 `MM2` 是两个中间人进程的 PID。中间人进程的代码，看起来像下面这样：
+
+```erlang
+loop(Socket, Pid) ->
+    receive
+        {tcp, Socket, Bin} ->
+            Pid ! {chan, self(), binary_to_term(Bin)},
+            loop(Socket, Pid);
+        {tcp_closed, Socket} ->
+            Pid ! {chan_closed, self()};
+        close ->
+            gen_tcp:close(Socket);
+        {send, T} ->
+            gen_tcp:send(Socket, [term_to_binary(T)]),
+            loop(Socket, Pid)
+    end.
+```
+
+这个循环被用作套接字数据世界，与 Erlang 消息传递世界的接口。咱们可在 [`lib_chan_mm`](#lib_chan_mm) 中，找到 `lib_chan_mm` 的完整代码。相比这里给出的代码，完整代码稍微复杂一些，但原理是一样的。唯一的区别在与，我们添加了一些用于跟踪消息的代码，以及一些接口例程。
+
+
+### `lib_chan_cs`
+
+
+`lib_chan_cs` 负责建立客户端与服务器的通信。他导出的两个重要例程如下：
+
+
+- `start_raw_server(Port, Max, Fun, PacketLength)`
+
+    这个例程会在 `Port` 上启动一个监听连接的监听器。最多 `Max` 个同时会话被允许。`Fun` 是一个 1 元函数；当某个连接启动时，`Fun(Socket)` 会被执行。套接字通信会假设一个长度为 `PacketLength` 的数据包。
+
+
+- `start_raw_client(Host, Port, PacketLength) -> {ok, Socket} | {error, Why}`
+
+    这个例程会尝试连接到某个以 `start_raw_server` 打开的端口。
+
+
+`lib_chan_cs` 的代码，遵循了 [并行服务器](../part-iv/Ch17-programming_with_sockets.md#parall_server) 中描述的模式，但此外他还会追踪同时打开连接的最大数量。这个小细节虽然在概念上很简单，却增加了二十多行看起来相当奇怪，捕获退出等的代码。像这样的代码一团糟，不过不用担心；他完成了他的工作，并对该模组的用户隐藏了复杂性。
+
+### `lib_chan_auth`
+
+
+该模组实现了一种简单形式的挑战/响应认证。挑战/响应的认证，基于与服务名名字相关联的共享秘密概念。要演示其工作原理，我们将假定有项名为 `math`，有着共享秘密 `qwerty` 的服务。
+
+当某个客户端打算使用服务 `math` 时，那么该客户端就必须向服务器证明，他们知道共享秘密。这个过程如下进行：
+
+1. 客户端发送一次请求到服务器，表明他想要使用 `math` 服务；
+
+2. 服务器会计算出一个随机字符串 `C` 并将其发送给客户端。这就是 *挑战*。该字符串由 `lib_chan_ auth:make_challenge()` 函数计算得出。我们可以交互式地使用他，看看他做了些什么。
+
+    ```erlang
+    1> lib_chan_auth:make_challenge().
+    "ynsbrxyuavrknszkretvjvqao"
+    ```
+
+3. 客户端收到这个字符串 (`C`) ，并计算出响应 (`R`)，其中 `R = MD5(C ++ Secret)`。`R` 是使用 `lib_chan_auth:make_response` 计算出的。下面是个示例：
+
+    ```erlang
+    2> R = lib_chan_auth:make_response(C, "qwerty").
+    "58565dbdf3328f7d9b9869a2c47eb699"
+    ```
+
+4. 响应会被发回服务器。服务器收到该响应，并通过计算该响应的预期值，检查其是否正确。这是在 `lib_chan_auth:is_response_correct` 中完成的。
+
+    ```erlang
+    3> lib_chan_auth:is_response_correct(C, R, "qwerty").
+    true
+    ```
+
+## `lib_chan` 的代码
+
+
+现在是代码时间。
+
+
+### `lib_chan`
+
+```erlang
+{{#include ../../projects/appendix/src/lib_chan.erl}}
+```
+
+### `lib_chan_cs`
+
+```erlang
+{{#include ../../projects/appendix/src/lib_chan_cs.erl}}
+```
+
+
+### `lib_chan_mm`
+
+```erlang
+{{#include ../../projects/appendix/src/lib_chan_mm.erl}}
+```
+
+
+### `lib_chan_auth`
+
+```erlang
+{{#include ../../projects/appendix/src/lib_chan_auth.erl}}
+```
+

projects/appendix/src/lib_chan_auth.erl

@@ -0,0 +1,7 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<comment version="3.0">
+  <caption/>
+  <note/>
+  <place/>
+  <categories/>
+</comment>

projects/appendix/src/lib_md5.erl

@@ -226,7 +226,7 @@ ok
 Server socket closed
 ```
 
-### 顺序与并行服务器
+### 顺序服务器与并行服务器
 
 在上一小节中，我们构造了个只接受一个连接并随后终止的服务器。稍微修改一下这些代码，我们就可以构造出两种不同类型的服务器。
 
@@ -273,6 +273,7 @@ loop(..) -> %% as before
 我们只给出的是启动服务器的代码。停止服务器很简单（停止并行服务器也很简单）；只要杀死启动服务器的进程。`gen_tcp` 会将自身链接到控制进程，并在控制进程死亡时，他就会关闭套接字。
 
 
+<a name="parall_server"></a>
 **并行服务器**
 
 构造并行服务器的诀窍在于，当每次 `gen_tcp:accept` 获取一个新连接时，都立即生成一个新的进程。