1 | [![Build Status](https://travis-ci.org/node-pinus/pinus-rpc.svg?branch=master)](https://travis-ci.org/node-pinus/pinus-rpc)
|
2 |
|
3 | #pinus-rpc - rpc framework for pinus
|
4 |
|
5 | pinus-rpc is the low level RPC framework for pinus project. It contains two parts: client and server.
|
6 |
|
7 | The client part generates the RPC client proxy, routes the message to the appropriate remote server and manages the network communications. Support add proxies and remote server information dynamically.
|
8 |
|
9 | The server part exports the remote services, dispatches the remote requests to the services and also manages the network communications.
|
10 |
|
11 | And the remote service codes would loaded by pinus-loader module and more details please access this [link](https://github.com/node-pinus/pinus-loader).
|
12 |
|
13 | + Tags: node.js
|
14 |
|
15 | ##Installation
|
16 | ```
|
17 | npm install pinus-rpc
|
18 | ```
|
19 |
|
20 | ##Usage
|
21 | ###Server
|
22 | ``` javascript
|
23 | var Server = require('pinus-rpc').server;
|
24 |
|
25 | // remote service path info list
|
26 | var paths = [
|
27 | {namespace: 'user', path: __dirname + '/remote/test'}
|
28 | ];
|
29 |
|
30 | var port = 3333;
|
31 |
|
32 | var server = Server.create({paths: paths, port: port});
|
33 | server.start();
|
34 | console.log('rpc server started.');
|
35 | ```
|
36 |
|
37 | ###Client
|
38 | ``` javascript
|
39 | var Client = require('pinus-rpc').client;
|
40 |
|
41 | // remote service interface path info list
|
42 | var records = [
|
43 | {namespace: 'user', serverType: 'test', path: __dirname + '/remote/test'}
|
44 | ];
|
45 |
|
46 | // server info list
|
47 | var servers = [
|
48 | {id: 'test-server-1', serverType: 'test', host: '127.0.0.1', port: 3333}
|
49 | ];
|
50 |
|
51 | // route parameter passed to route function
|
52 | var routeParam = null;
|
53 |
|
54 | // route context passed to route function
|
55 | var routeContext = servers;
|
56 |
|
57 | // route function to caculate the remote server id
|
58 | var routeFunc = function(routeParam, msg, routeContext, cb) {
|
59 | cb(null, routeContext[0].id);
|
60 | };
|
61 |
|
62 | var client = Client.create({routeContext: routeContext, router: routeFunc});
|
63 |
|
64 | client.start(function(err) {
|
65 | console.log('rpc client start ok.');
|
66 |
|
67 | client.addProxies(records);
|
68 | client.addServers(servers);
|
69 |
|
70 | client.proxies.user.test.service.echo(routeParam, 'hello', function(err, resp) {
|
71 | if(err) {
|
72 | console.error(err.stack);
|
73 | }
|
74 | console.log(resp);
|
75 | });
|
76 | });
|
77 | ```
|
78 |
|
79 | ##Server API
|
80 | ###Server.create(opts)
|
81 | Create a RPC server instance. Intitiate the instance and acceptor with the configure.
|
82 | ###Parameters
|
83 | + opts.port - rpc server listening port.
|
84 | + opts.paths - remote service path infos, format: [{namespace: remote service namespace, path: remote service path}, ...].
|
85 | + opts.context - remote service context.
|
86 | + opts.acceptorFactory(opts, msgCB) - (optional) acceptor factory method. opts.port:port that acceptor would listen,opts.services:loaded remote services,format: {namespace: {name: service}}. msgCB(msg, cb): remote request arrived callback. the method should return a acceptor instance.
|
87 |
|
88 | ###server.start
|
89 | Start the remote server instance.
|
90 |
|
91 | ###server.stop
|
92 | Stop the remote server instance and the acceptor.
|
93 |
|
94 | ###Acceptor
|
95 | Implement the low level network communication with specified protocol. Customize the protocol by passing an acceptorFactory to return different acceptors.
|
96 |
|
97 | ###acceptor.listen(port)
|
98 | Listen the specified port.
|
99 |
|
100 | ###acceptor.close
|
101 | Stop the acceptor.
|
102 |
|
103 | ##Client API
|
104 | ###Client.create(opts)
|
105 | Create an RPC client instance which would generate proxies for the RPC client.
|
106 | ####Parameters
|
107 | + opts.context - context for mailbox.
|
108 | + opts.routeContext - (optional)context for route function.
|
109 | + opts.router(routeParam, msg, routeContext, cb) - (optional) route function which decides the RPC message should be send to which remote server. routeParam: route parameter, msg: RPC descriptioin message, routeContext: opts.routeContext.
|
110 | + opts.mailBoxFactory(serverInfo, opts) - (optional) mail box factory method.
|
111 |
|
112 | ###client.addProxies(records)
|
113 | Load new proxy codes.
|
114 | ####Parameters
|
115 | + records - new proxy code configure information list。Format: [{namespace: service_name_space, serverType: remote_server_type, path: path_to_remote_service_interfaces}];
|
116 |
|
117 | ###client.addServers(servers)
|
118 | Add new remote server informations.
|
119 | ####Parameters
|
120 | + servers - remote server information list. Format: [{id: remote_server_id, serverType: remote_server_type, host: remote_server_host, port: remote_server_port}]
|
121 |
|
122 | ###client.start(cb)
|
123 | Start the RPC client.
|
124 |
|
125 | ###client.stop
|
126 | Stop the RPC client and stop all the mail box connections to remote servers.
|
127 |
|
128 | ###client.rpcInvoke(serverId, msg, cb)
|
129 | Invoke an RPC request.
|
130 | ####Parameters
|
131 | + serverId - remote server id.
|
132 | + msg - RPC description message. format: {namespace: remote service namespace, serverType: remote server type, service: remote service name, method: remote service method name, args: remote service args}.
|
133 | + cb - remote service callback function.
|
134 |
|
135 | ###MailBox
|
136 | Implement the low level network communication with remote server. A mail box instance stands for a remote server. Customize the protocol by passing a mailBoxFactory parameter to client to return different mail box instances.
|
137 |
|
138 | ###mailbox.connect(cb)
|
139 | Connect to the remote server.
|
140 |
|
141 | ###mailbox.close
|
142 | Close mail box instance and disconnect with the remote server.
|
143 |
|
144 | ###mailbox.send(msg, opts, cb)
|
145 | Send the RPC message to the associated remote server.
|
146 | ####Parameters
|
147 | + msg - RPC description message, see also clienet.rpcInvoke.
|
148 | + opts - reserved.
|
149 | + cb - RPC callback function. |
\ | No newline at end of file |