Skip to content

Commit 143a8be

Browse files
pocesarpocesar
committed
add breaking change notice
1 parent c320031 commit 143a8be

File tree

1 file changed

+166
-161
lines changed

1 file changed

+166
-161
lines changed

‎README.md‎

Lines changed: 166 additions & 161 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,166 @@
1-
[![Build Status](https://travis-ci.org/pocesar/node-jsonrpc2.svg?branch=master)](https://travis-ci.org/pocesar/node-jsonrpc2)
2-
3-
[![NPM](https://nodei.co/npm/json-rpc2.svg?downloads=true)](https://nodei.co/npm/json-rpc2/)
4-
5-
# node-jsonrpc2
6-
7-
JSON-RPC 2.0 server and client library, with `HTTP` (with `Websocket` support) and `TCP` endpoints
8-
9-
This fork is a rewrite with proper testing framework, linted code, compatible with node 0.8.x and 0.10.x, class inheritance, and added functionalities
10-
11-
## Tools
12-
13-
Check [jsonrpc2-tools](https://www.npmjs.org/package/jsonrpc2-tools) for some nice additions to this module.
14-
15-
## Install
16-
17-
To install node-jsonrpc2 in the current directory, run:
18-
19-
```bash
20-
npm install json-rpc2 --save
21-
```
22-
23-
## Usage
24-
25-
Firing up an efficient JSON-RPC server becomes extremely simple:
26-
27-
```js
28-
var rpc = require('json-rpc2');
29-
30-
var server = rpc.Server.$create({
31-
'websocket': true, // is true by default
32-
'headers': { // allow custom headers is empty by default
33-
'Access-Control-Allow-Origin': '*'
34-
}
35-
});
36-
37-
function add(args, opt, callback) {
38-
callback(null, args[0] + args[1]);
39-
}
40-
41-
server.expose('add', add);
42-
43-
// you can expose an entire object as well:
44-
45-
server.expose('namespace', {
46-
'function1': function(){},
47-
'function2': function(){},
48-
'function3': function(){}
49-
});
50-
// expects calls to be namespace.function1, namespace.function2 and namespace.function3
51-
52-
// listen creates an HTTP server on localhost only
53-
server.listen(8000, 'localhost');
54-
```
55-
56-
And creating a client to speak to that server is easy too:
57-
58-
```js
59-
var rpc = require('json-rpc2');
60-
61-
var client = rpc.Client.$create(8000, 'localhost');
62-
63-
// Call add function on the server
64-
65-
client.call('add', [1, 2], function(err, result) {
66-
console.log('1 + 2 = ' + result);
67-
});
68-
```
69-
70-
Create a raw (socket) server using:
71-
72-
```js
73-
var rpc = require('json-rpc2');
74-
75-
var server = rpc.Server.$create();
76-
77-
// non-standard auth for RPC, when using this module using both client and server, works out-of-the-box
78-
server.enableAuth('user', 'pass');
79-
80-
// Listen on socket
81-
server.listenRaw(8080, 'localhost');
82-
```
83-
84-
## Extend, overwrite, overload
85-
86-
Any class can be extended, or used as a mixin for new classes, since it uses [ES5Class](http://github.com/pocesar/ES5-Class) module.
87-
88-
For example, you may extend the `Endpoint` class, that automatically extends `Client` and `Server` classes.
89-
Extending `Connection` automatically extends `SocketConnection` and `HttpServerConnection`.
90-
91-
```js
92-
var rpc = require('json-rpc2');
93-
94-
rpc.Endpoint.$include({
95-
'newFunction': function(){
96-
97-
}
98-
});
99-
100-
var
101-
server = rpc.Server.$create(),
102-
client = rpc.Client.$create();
103-
104-
server.newFunction(); // already available
105-
client.newFunction(); // already available
106-
```
107-
108-
To implement a new class method (that can be called without an instance, like `rpc.Endpoint.newFunction`):
109-
110-
```js
111-
var rpc = require('json-rpc2');
112-
113-
rpc.Endpoint.$implement({
114-
'newFunction': function(){
115-
}
116-
});
117-
118-
rpc.Endpoint.newFunction(); // available
119-
rpc.Client.newFunction(); // every
120-
rpc.Server.newFunction(); // where
121-
```
122-
123-
Don't forget, when you are overloading an existing function, you can call the original function using `$super`
124-
125-
```js
126-
var rpc = require('json-rpc2');
127-
128-
rpc.Endpoint.$implement({
129-
'trace': function($super, direction, message){
130-
$super(' (' + direction + ')', message); //call the last defined function
131-
}
132-
});
133-
```
134-
135-
And you can start your classes directly from any of the classes
136-
137-
```js
138-
var MyCoolServer = require('json-rpc2').Server.$define('MyCoolServer', {
139-
myOwnFunction: function(){
140-
},
141-
}, {
142-
myOwnClassMethod: function(){
143-
}
144-
}); // MyCoolServer will contain all class and instance functions from Server
145-
146-
MyCoolServer.myOwnClassMethod(); // class function
147-
MyCoolServer.$create().myOwnFunction(); // instance function
148-
```
149-
150-
## Debugging
151-
152-
This module uses the [debug](http://github.com/visionmedia/debug) package, to debug it, you need to set the Node
153-
environment variable to jsonrpc, by setting it in command line as `set DEBUG=jsonrpc` or `export DEBUG=jsonrpc`
154-
155-
## Examples
156-
157-
To learn more, see the `examples` directory, peruse `test/jsonrpc-test.js`, or
158-
simply "Use The Source, Luke".
159-
160-
More documentation and development is on its way.
161-
1+
[![Build Status](https://travis-ci.org/pocesar/node-jsonrpc2.svg?branch=master)](https://travis-ci.org/pocesar/node-jsonrpc2)
2+
3+
[![NPM](https://nodei.co/npm/json-rpc2.svg?downloads=true)](https://nodei.co/npm/json-rpc2/)
4+
5+
# node-jsonrpc2
6+
7+
JSON-RPC 2.0 server and client library, with `HTTP` (with `Websocket` support) and `TCP` endpoints
8+
9+
This fork is a rewrite with proper testing framework, linted code, compatible with node 0.8.x and 0.10.x, class inheritance, and added functionalities
10+
11+
## Tools
12+
13+
Check [jsonrpc2-tools](https://www.npmjs.org/package/jsonrpc2-tools) for some nice additions to this module.
14+
15+
## Install
16+
17+
To install node-jsonrpc2 in the current directory, run:
18+
19+
```bash
20+
npm install json-rpc2 --save
21+
```
22+
23+
## Changes from 0.x
24+
25+
Before, the `id` member was permissive and wouldn't actually adhere to the RFC, allowing anything besides `undefined`.
26+
If your application relied on weird id constructs other than `String`, `Number` or `null`, it might break if you update to 1.x
27+
28+
## Usage
29+
30+
Firing up an efficient JSON-RPC server becomes extremely simple:
31+
32+
```js
33+
var rpc = require('json-rpc2');
34+
35+
var server = rpc.Server.$create({
36+
'websocket': true, // is true by default
37+
'headers': { // allow custom headers is empty by default
38+
'Access-Control-Allow-Origin': '*'
39+
}
40+
});
41+
42+
function add(args, opt, callback) {
43+
callback(null, args[0] + args[1]);
44+
}
45+
46+
server.expose('add', add);
47+
48+
// you can expose an entire object as well:
49+
50+
server.expose('namespace', {
51+
'function1': function(){},
52+
'function2': function(){},
53+
'function3': function(){}
54+
});
55+
// expects calls to be namespace.function1, namespace.function2 and namespace.function3
56+
57+
// listen creates an HTTP server on localhost only
58+
server.listen(8000, 'localhost');
59+
```
60+
61+
And creating a client to speak to that server is easy too:
62+
63+
```js
64+
var rpc = require('json-rpc2');
65+
66+
var client = rpc.Client.$create(8000, 'localhost');
67+
68+
// Call add function on the server
69+
70+
client.call('add', [1, 2], function(err, result) {
71+
console.log('1 + 2 = ' + result);
72+
});
73+
```
74+
75+
Create a raw (socket) server using:
76+
77+
```js
78+
var rpc = require('json-rpc2');
79+
80+
var server = rpc.Server.$create();
81+
82+
// non-standard auth for RPC, when using this module using both client and server, works out-of-the-box
83+
server.enableAuth('user', 'pass');
84+
85+
// Listen on socket
86+
server.listenRaw(8080, 'localhost');
87+
```
88+
89+
## Extend, overwrite, overload
90+
91+
Any class can be extended, or used as a mixin for new classes, since it uses [ES5Class](http://github.com/pocesar/ES5-Class) module.
92+
93+
For example, you may extend the `Endpoint` class, that automatically extends `Client` and `Server` classes.
94+
Extending `Connection` automatically extends `SocketConnection` and `HttpServerConnection`.
95+
96+
```js
97+
var rpc = require('json-rpc2');
98+
99+
rpc.Endpoint.$include({
100+
'newFunction': function(){
101+
102+
}
103+
});
104+
105+
var
106+
server = rpc.Server.$create(),
107+
client = rpc.Client.$create();
108+
109+
server.newFunction(); // already available
110+
client.newFunction(); // already available
111+
```
112+
113+
To implement a new class method (that can be called without an instance, like `rpc.Endpoint.newFunction`):
114+
115+
```js
116+
var rpc = require('json-rpc2');
117+
118+
rpc.Endpoint.$implement({
119+
'newFunction': function(){
120+
}
121+
});
122+
123+
rpc.Endpoint.newFunction(); // available
124+
rpc.Client.newFunction(); // every
125+
rpc.Server.newFunction(); // where
126+
```
127+
128+
Don't forget, when you are overloading an existing function, you can call the original function using `$super`
129+
130+
```js
131+
var rpc = require('json-rpc2');
132+
133+
rpc.Endpoint.$implement({
134+
'trace': function($super, direction, message){
135+
$super(' (' + direction + ')', message); //call the last defined function
136+
}
137+
});
138+
```
139+
140+
And you can start your classes directly from any of the classes
141+
142+
```js
143+
var MyCoolServer = require('json-rpc2').Server.$define('MyCoolServer', {
144+
myOwnFunction: function(){
145+
},
146+
}, {
147+
myOwnClassMethod: function(){
148+
}
149+
}); // MyCoolServer will contain all class and instance functions from Server
150+
151+
MyCoolServer.myOwnClassMethod(); // class function
152+
MyCoolServer.$create().myOwnFunction(); // instance function
153+
```
154+
155+
## Debugging
156+
157+
This module uses the [debug](http://github.com/visionmedia/debug) package, to debug it, you need to set the Node
158+
environment variable to jsonrpc, by setting it in command line as `set DEBUG=jsonrpc` or `export DEBUG=jsonrpc`
159+
160+
## Examples
161+
162+
To learn more, see the `examples` directory, peruse `test/jsonrpc-test.js`, or
163+
simply "Use The Source, Luke".
164+
165+
More documentation and development is on its way.
166+

0 commit comments

Comments
 (0)