diff --git a/.travis.yml b/.travis.yml index c1c8f29..fc6eda5 100644 --- a/.travis.yml +++ b/.travis.yml @@ -6,8 +6,6 @@ git: depth: 3 node_js: - #- '0.10' # Support dropped on 0.6.0 - #- 0.12 # Support dropped on 0.6.0 - 4 - 6 - 8 diff --git a/README.md b/README.md index 3223bba..0ae17ab 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,5 @@ -node-smpp -========= +# node-smpp + SMPP client and server implementation in node.js. [![Build Status](https://api.travis-ci.com/farhadi/node-smpp.svg?branch=master)](https://app.travis-ci.com/github/farhadi/node-smpp) @@ -7,8 +7,8 @@ SMPP client and server implementation in node.js. [![devDependency Status](https://david-dm.org/farhadi/node-smpp/dev-status.svg)](https://david-dm.org/farhadi/node-smpp#info=devDependencies) [![Coverage Status](https://coveralls.io/repos/github/farhadi/node-smpp/badge.svg?branch=master)](https://coveralls.io/github/farhadi/node-smpp?branch=master) -Introduction ------------- +## Introduction + This is a complete implementation of SMPP v5.0 in node.js, with support for custom commands and TLVs. @@ -21,13 +21,14 @@ the names defined in SMPP specification. So get a copy of [SMPP v5.0 Specification](https://smpp.org/SMPP_v5.pdf) for a list of available operations and their parameters. -Installation ------------- +## Installation - npm install smpp +``` +npm install smpp +``` + +## Usage -Usage ------ ### Creating a SMPP session ``` javascript @@ -88,10 +89,13 @@ var server = smpp.createServer({ server.listen(2775); ``` -It's very important to listen for session errors, not listening for error events will terminate the program. +It's very important to listen for session errors, not listening for error events +will terminate the program. ### Debug -To enable a simple debug of ingoing/outgoing messages pass `debug: true` as server/client option. Debug is disabled by default. + +To enable a simple debug of ingoing/outgoing messages pass `debug: true` as +server/client option. Debug is disabled by default. Alternatively, you can listen for the `debug` event and write your own implementation: ``` javascript @@ -110,8 +114,11 @@ var options = { } ``` -### Handling client connection errors: -In case of errors while trying to connect, an `error` event will be emitted by the session and the program will be terminated if it's not listened. This is how you should check for errors. +### Handling client connection errors + +In case of errors while trying to connect, an `error` event will be emitted by the session +and the program will be terminated if it's not listened. This is how you should check for +errors. ``` javascript session.on('error', function(e) { @@ -126,33 +133,40 @@ session.on('error', function(e) { }); ``` -### Connection timeout: +### Connection timeout -By default the socket will be dropped after 30000 ms if it doesn't connect. A `connectTimeout` option can be sent when making connections with the server in order to change this setting. +By default the socket will be dropped after 30000 ms if it doesn't connect. +A `connectTimeout` option can be sent when making connections with the server in order +to change this setting. -### Proxy protocol (v1) support (experimental): -[Proxy Protocol header specs](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) +### Proxy protocol -Pass `enable_proxy_protocol_detection: true` as server option. +[Proxy Protocol v1](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) is now +supported as an _experimental_ feature, both for TCP4 and TCP6. -- Only Proxy protocol v1 is supported. Both TCP4 & TCP6. -- `session.remoteAddress` will contain the proxied source ip. -- `session.proxyProtocolProxy` will contain the proxy ip. -- Even with proxy protocol detection enabled the server will understand non-proxied requests. -- Tests are provided to make sure TCP4 & TCP6 proxy headers are handled correctly. Tests configures the servers to automatically inject fake proxy protocol headers before establishing the net/tls connection. + Pass `enable_proxy_protocol_detection: true` as server option to enable proxy protocol + detection, if the option is not provided the feature is completely ignored. + +- `session.remoteAddress` will contain the proxied source IP. +- `session.proxyProtocolProxy` will contain the proxy IP. +- Even with proxy protocol detection enabled the server will understand non-proxied +requests. - Security: Proxy CIDRs validation is yet to be implemented. -- Uses [findhit-proxywrap](https://www.npmjs.com/package/findhit-proxywrap), a third party library to wrap the net/tls implementations and decode the proxy-protocol header before forwarding it to the standard implementations. -- Experimental feature: if no `enable_proxy_protocol_detection: true` option is provided, standard servers are used and the implementation is completely ignored. +- Uses [findhit-proxywrap](https://www.npmjs.com/package/findhit-proxywrap), a third +party library to wrap the net/tls implementations and decode the proxy-protocol +- header before forwarding it to the standard implementations. + +#### Compatibility issues -#### Compatibility issues: -- Support for Nodejs < v4 (2015) has been dropped: Changes to supported Nodejs versions due compatibility issues of findhit-proxywrap. -- On proxied, non-tls connections (with Nodejs < v8): Proxywrap shows some misbehaviour with the way this library inherits from the net server, the socket looses the ability to emit events. As a minor-fix, the `socket.emit` method is backed up and restored after the proxying to the net server, making everything work as expected. +- On proxied, non-tls connections (with Nodejs < v8): Proxywrap shows some misbehaviour +with the way this library inherits from the net server, the socket looses the ability +to emit events. As a minor-fix, the `socket.emit` method is backed up and restored +after the proxying to the net server, making everything work as expected. -Encodings ---------- +## Encodings This smpp implementation supports 3 encodings: `ASCII` (GSM 03.38), `LATIN1`, and `UCS2`. -Respective data_coding for these encodings are `0x01`, `0x03`, and `0x08`. +data_coding for these encodings are `0x01`, `0x03`, and `0x08` respectively. Default encoding for `data_coding:0` is `ASCII`. You can change it as follows: @@ -171,8 +185,7 @@ delete smpp.encodings.ASCII; You can also manually convert a message to a buffer and pass it as `short_message` or `message_payload` parameter to bypass automatic message encoding. -API -------- +## API ### smpp.connect(url, [callback]) Creates a new smpp session using the specified connection url. @@ -283,7 +296,7 @@ the server has been bound. Emitted when a new session connection is established. `session` is an instance of `smpp.Session`. -*for other server methods/events documentations see node's `net.Server` docs.* +_for other server methods/events documentations see node's `net.Server` docs._ ### smpp.PDU This is the base object for a PDU request or response. @@ -299,36 +312,36 @@ integers) will be used. For the type of the parameters note the following rules: -* For `Integer` parameters (no matter what the length is) you must specify a +- For `Integer` parameters (no matter what the length is) you must specify a value of type `number` in JavaScript. -* For `Octet-String` and `COctet-String` parameters you can specify either a +- For `Octet-String` and `COctet-String` parameters you can specify either a `Buffer` or a `String`. -* For the fields that accept SMPP Time Format (`broadcast_end_time`, +- For the fields that accept SMPP Time Format (`broadcast_end_time`, `schedule_delivery_time`, `validity_period`, `final_date`) you can specify a Javascript Date instance which will be automatically converted to a SMPP absolute time string. For relative times you don't need to specify the whole string, specifying a portion of it is enough. for example '0430' will be converted to '000000000430000R'. -* For `short_message` and `message_payload` fields you can specify a buffer or a +- For `short_message` and `message_payload` fields you can specify a buffer or a string or an object containing `udh` and `message` properties, while `udh` is a buffer and `message` is either a string or a buffer. strings will be automatically encoded using ASCII, LATIN1, or UCS2 depending on their characters. `data_coding` (if not specified) will be automatically set to 0x01, 0x03, or 0x08 for ASCII, LATIN1, and UCS2 encodings respectively. Also UDH indicator bit in `esm_class` is automatically set if `udh` exists. -* `sm_length` parameter is not needed. It will be automatically set depending on +- `sm_length` parameter is not needed. It will be automatically set depending on the length of the `short_message`. -* `dest_address` parameter in `submit_multi` operation must be an array of +- `dest_address` parameter in `submit_multi` operation must be an array of objects containing either `dest_addr_ton`, `dest_addr_npi` and, `destination_addr` properties or `dl_name` property for SME addresses or Distribution Lists respectively. -* `unsuccess_sme` parameter in `submit_multi_resp` operation must be an array of +- `unsuccess_sme` parameter in `submit_multi_resp` operation must be an array of objects containing `dest_addr_ton`, `dest_addr_npi`, `destination_addr` and, `error_status_code` properties. -* `number_of_dests` and `no_unsuccess` parameters are not needed. They will be +- `number_of_dests` and `no_unsuccess` parameters are not needed. They will be automatically set depending on the `dest_address` and `unsuccess_sme` parameters respectively. -* TLV parameters which can be specified multiple times +- TLV parameters which can be specified multiple times (e.g. `broadcast_area_identifier`), must be specified as an array, even if you want to specifiy just one item. @@ -359,11 +372,19 @@ session.on('enquire_link', function(pdu) { }); ``` -Roadmap -------- -* More test coverage. -* Add some usage examples (e.g client, server, and cluster examples) +## Upgrade notes + +### upgrade to version 0.6.0 + +- Support for Nodejs < v4 (2015) has been dropped due compatibility issues with +findhit-proxywrap library +- Proxy protocol v1 support has been added as an experimental feature. Disabled by default, +will be completely ignored if not enabled. + +## Roadmap + +- Add some usage examples (e.g client, server, and cluster examples) + +## License -License -------- node-smpp is released under the MIT license. diff --git a/lib/smpp.js b/lib/smpp.js index fa4f82e..7a7c980 100644 --- a/lib/smpp.js +++ b/lib/smpp.js @@ -363,7 +363,7 @@ function ProxySecureServer(options, listener) { Server.call(this, options, listener); } -// Standard servers without proyxy protocol support +// Standard servers without proxy protocol support util.inherits(Server, net.Server); util.inherits(SecureServer, tls.Server);