Terminologies

Pomelo has its own terminology, and here we will give a brief explanation of terminology, giving readers an intuitive concept, clarifying confusion while reading this tutorial.

Common Terms

Gate server

Generally the gate server do not involve rpc call, that means it do not have port field in its configuration item, only has the clientPort field, and it is just use for frontend load balancing. Clients first often send requests to the gate server, and the gate server will assign client a specific connector server.The specific allocation strategies can be generated by developers, so that you can achieve the load balancing among various connector servers.

Connector server

Connector server is responsible for receiving connection requests, creating connections with clients, maintaining clients' session information, receiving client requests and forwarding the requests to a specific backend server according to user-configured routing policy. When the backend server has processed the request or need to push messages to clients, connector servers will send messages to clients as an intermediate role. Connector server has clientPort and port, with clientPort is used for listening to client connections, and port is used to provide backend service.

Application server

Gate server and connector server are called frontend servers. Application server is backend server, which performs the application logic, providing services to clients. Of course, the clients' requests are routed through frontend servers. Backend servers will interact with each other through rpc calls. Since the backend server does not have a direct connection with clients, so the backend server only has the port field.

Master server

Master server is responsible for loading configuration files, starting the server cluster through the configuration file, and managing all other servers.

Rpc call

Pomelo uses rpc call for interprocess communication, the rpc call in pomelo can be divided into two categories by the namespace, the sys rpc call for the system, which is transparent to users, the system rpc call are:

• Backend servers push session information request to frontend servers
• Backend servers push messages to frontend servers through channel
• Frontend servers forward client requests to backend servers In addition to system rpc call, the rest are belong to user-defined rpc call, and this kind of rpc require users to complete the rpc server code.

route,router

Route is used to identify a specific service or the position where clients accept messages from servers. For server side, its form is generally . . , such as "chat.chatHandler.send", chat is the server type , chatHandler is a Handler defined in chat server, send is a method in Handler.For the client side, its general form is onXXX, when servers push messages, the client side would have the corresponding callback. Generally speaking the same type application server is not single, when a client request arrives, the frontend server will dispatch the client requests to a specific backend server, which requires a distributed routing function router. The router that can use user 's session as well as the contents of its request , do some calculations , it will map it to a specific application server id. The route can be invoked through the application of a type of server to configure their router. If you do not configure it, pomelo will use a default router which uses session routing function inside the uid fields, calculates fields crc32 checksums uid. Note that there is a trap that if the session is not bind with uid, at this time the uid field is undefined, and this may cause all requests are routed to the same server. So in the actual development developers still need to configure their own router.

Session, MockLocalSession, LocalSession， SessionService， LocalSessionService

In pomelo, the concept of these three kinds of session and two kinds of service: SessionService and LocalSessionService, is the most confusing place. And here we try to give some explanation, so you understand much more clearly. Session is a abstraction of client connection , its fields are as follow:

{
    id : <session id> // readonly
    frontendId : <frontend server id> // readonly
    uid : <bound uid> // readonly
    settings : <key-value map> // read and write  
    __socket__ : <raw_socket>
    __state__ : <session state>

    // ...
}

• Id is the session id, which is unique in global and generated by the increment way;
• FrontendId is the frontend server id which maintains the session;
• Uid is the user id which is binded with the session;
• __socket__ is a reference to the native socket;
• __state__ is used to indicate the current state of session.
• Settings is a key-value map, which is used to keep some custom attributes of session.

From the above analysis, a session is once established, then the field id, frontendId, __socket__,__state__, uid are identified, and they should only readonly. The settings should not be freely modified. Therefore, in the frontend server, we introduce the MockLocalSession, which can be seen as a puppet of real session in frontend server, MockLocalSession fields as follows:

{
    id : <session id> // readonly
    frontendId : <frontend server id> // readonly
    uid : <bound uid> // readonly
    settings : <key-value map> // read and write  
}

The following is MockLocalSession's function:

• Settings can be set by MockLocalSession, and the values of settings in MockLocalSession can be synchronized to the real session by invoking the push method of MockLocalSession;
• You can bind uid to the session by invoking the bind method of MockLocalSession;
• Of course, the read-only fields in session can also be accessed via MockLocalSession, but it can not send the changes to the original session.