1 | =head1 Message Passing for the Non-Blocked Mind |
1 | =head1 Message Passing for the Non-Blocked Mind |
2 | |
2 | |
3 | =head1 Introduction and Terminology |
3 | =head1 Introduction and Terminology |
4 | |
4 | |
5 | This is a tutorial about how to get the swing of the new L<AnyEvent::MP> |
5 | This is a tutorial about how to get the swing of the new L<AnyEvent::MP> |
6 | module. Which allows us to transparently pass messages to our own process |
6 | module, which allows us to transparently pass messages to our own process |
7 | and to other processes on another or the same host. |
7 | and to other processes on another or the same host. |
8 | |
8 | |
9 | What kind of messages? Well, basically a message here means a list of |
9 | What kind of messages? Well, basically a message here means a list of |
10 | Perl strings, numbers, hashes and arrays, mostly everything that can be |
10 | Perl strings, numbers, hashes and arrays, anythin everything that can be |
11 | expressed as a L<JSON> text (as JSON is used by default in the protocol). |
11 | expressed as a L<JSON> text (as JSON is used by default in the protocol). |
12 | |
12 | |
13 | And next you might ask: between which entities are those messages |
13 | And next you might ask: between which entities are those messages |
14 | being "passed"? Effectively between I<nodes>: a nodes is basically a |
14 | being "passed"? Effectively between I<nodes>: a nodes is basically a |
15 | process/program that use L<AnyEvent::MP> and can run either on the same or |
15 | process/program that use L<AnyEvent::MP> and can run either on the same or |
16 | different hosts. |
16 | different hosts. |
17 | |
17 | |
18 | To make this more managable, every node can contain any number of |
18 | To make this more managable, every node can contain any number of |
19 | I<ports>: Ports are ultimately the receivers of your messages. |
19 | I<ports>: Ports are ultimately the receivers of your messages. |
20 | |
20 | |
21 | In this tutorial I'll show you how to write a simple chat server based on |
21 | In this tutorial I'll show you how to write a simple chat server based |
22 | L<AnyEvent::MP>. |
22 | on L<AnyEvent::MP>. This example is used because it nicely shows how to |
|
|
23 | organise a simple application, but keep in mind that every node trusts any |
|
|
24 | other, so this chat cannot be used to implement a real chat server and |
|
|
25 | client system, but it can be used to implement a distributed chat system |
|
|
26 | for example. |
23 | |
27 | |
24 | =head1 System Requirements and System Setup |
28 | =head1 System Requirements and System Setup |
25 | |
29 | |
26 | Before we can start we have to make sure some things work on your |
30 | Before we can start we have to make sure some things work on your |
27 | system. |
31 | system. |
28 | |
32 | |
29 | You should of course also make sure that L<AnyEvent> and L<AnyEvent::MP> |
33 | You should of course first make sure that L<AnyEvent> and L<AnyEvent::MP> |
30 | are installed. But how to do that is out of scope of this tutorial. |
34 | are installed. But how to do that is out of scope of this tutorial. |
31 | |
35 | |
32 | Then we have to setup a I<shared secret>: for two L<AnyEvent::MP> nodes to |
36 | Then we have to setup a I<shared secret>: for two L<AnyEvent::MP> nodes to |
33 | be able to communicate with each other and authenticate each other it is |
37 | be able to communicate with each other and authenticate each other it is |
34 | necessary to setup the same I<shared secret> for both of them. |
38 | necessary to setup the same I<shared secret> for both of them (use use TLS |
|
|
39 | certificates). |
35 | |
40 | |
36 | The easiest way is to use the F<aemp> utility: |
41 | The easiest way is to set this up is to use the F<aemp> utility: |
37 | |
42 | |
38 | aemp gensecret |
43 | aemp gensecret |
39 | |
44 | |
40 | This creates the F<$HOME/.perl-anyevent-mp> config file and generates a |
45 | This creates a F<$HOME/.perl-anyevent-mp> config file and generates a |
41 | random shared secret. You can copy this file to any other system and then |
46 | random shared secret. You can copy this file to any other system and then |
42 | communicate with it. You can also select your own shared secret (F<aemp |
47 | communicate with it. You can also select your own shared secret (F<aemp |
43 | setsecret>) and for increased security requirements you can even create |
48 | setsecret>) and for increased security requirements you can even create |
44 | a TLS certificate (F<aemp gencert>), causing conenctions to not just be |
49 | a TLS certificate (F<aemp gencert>), causing connections to not just be |
45 | authenticated, but also to be encrypted. |
50 | authenticated, but also to be encrypted. |
46 | |
51 | |
47 | Connections will only be successful when the nodes that want to connect to |
52 | Connections will only be successful when the nodes that want to connect to |
48 | each other have the same I<shared secret> (or successfully verify the TLS |
53 | each other have the same I<shared secret> (or successfully verify the TLS |
49 | certificate). |
54 | certificate of the other side). |
50 | |
55 | |
51 | B<If something does not work as expected, and for example tcpdump shows |
56 | B<If something does not work as expected, and for example tcpdump shows |
52 | that the connections are closed almost immediatly, you should make sure |
57 | that the connections are closed almost immediatly, you should make sure |
53 | that F<~/.perl-anyevent-mp> is the same on all hosts/user accounts that |
58 | that F<~/.perl-anyevent-mp> is the same on all hosts/user accounts that |
54 | you try to connect with each other!> |
59 | you try to connect with each other!> |
… | |
… | |
452 | |
457 | |
453 | Now, for the interested parties, let me explain some details about the protocol |
458 | Now, for the interested parties, let me explain some details about the protocol |
454 | that L<AnyEvent::MP> nodes use to communicate to each other. If you are not |
459 | that L<AnyEvent::MP> nodes use to communicate to each other. If you are not |
455 | interested you can skip this section. |
460 | interested you can skip this section. |
456 | |
461 | |
457 | Usually TCP is used for communication. Each I<node>, if configured to be a |
462 | Usually TCP is used for communication. Each I<node>, if configured to be |
458 | I<public> node with the C<become_public> function will listen on the configured |
463 | a I<public> node with the C<initialise_node> function will listen on the |
459 | TCP port (default is 4040). |
464 | configured TCP port (default is 4040). |
460 | |
465 | |
461 | If then one I<node> wants to send a message to another I<node> it will |
466 | If then one I<node> wants to send a message to another I<node> it will |
462 | connect to the host and port given in the I<port ID>. |
467 | connect to the host and port given in the I<port ID>. |
463 | |
468 | |
464 | Then some handshaking occurs to check whether both I<nodes> know the |
469 | Then some handshaking occurs to check whether both I<nodes> know the |