stmp v3.1.3

STMP

A lightweight real-time bidirectional framework.

Features

• Real real-time, no polling
• Koa like server side
• Simple and fast
• Transport layer transparent, supports TCP/WebSockets now
• Multiple transport layer support at the same time for server side

Install

yarn add stmp

# npm
npm i stmp

Example

Server side

import { STMPServer } from 'stmp';
import { TCPAdaptor } from 'stmp/lib/TCPAdaptor';
import net from 'net';

const tcpServer = new net.Server();

const server = new STMPServer([new TCPAdaptor(tcpServer)]);

server.use('test.echo', (ctx) => {
  ctx.output({ message: ctx.input.message });
});
server.use('test.push', (ctx) => {
  ctx.conn.push('push.server', { message: ctx.input.message });
});

tcpServer.listen(3000);

Client side

import { TCPClient } from 'stmp/lib/TCPClient';

const client = new TCPClient(3000, '127.0.0.1');

client.use('push.server', (ctx) => {
  console.log(ctx.input.message);
});

client.fetch('test.echo', { message: 'echo message' }).then((res) => {
  console.log(res.data.message);
});

client.push('test.push', { message: 'push message' });

// the console log result should be:
// 'echo message'
// 'push message'

API

You can see it at ./lib/.

Specification

Flow

Server Listen ---> Client Connect ---> Client Handshake ---> Server Handshake ---> Exchange Messages ---> Close

Handshake

1. client handshake request frame

   [LENGTH]<URL>[\nHEADER KEY: HEADER VALUE\n...]

2. server handshake response frame

   [LENGTH]<HANDSHAKE STATUS>[RESPONSE MESSAGE]

Note

1. WebSocketClient reuse WebSocket handshake frame

Exchange

Message kind:

• Request
• Response
• Push
• Close
• Ping

Message format:

1. Request/Push message

   [LENGTH][RESERVED(1)]<KIND><FOLLOW><FIN>[RESERVED(2)]<MESSAGE ID><ACTION>[PAYLOAD]

2. Response message

   [LENGTH][RESERVED(1)]<KIND><FOLLOW><FIN>[RESERVED(2)]<MESSAGE ID><RESPONSE STATUS>[SERVER LATENCY][PAYLOAD]

3. Ping message

   [LENGTH][RESERVED(1)]<KIND>[RESERVED(4)]<MESSAGE ID>

4. Close Message

   [LENGTH][RESERVED(1)]<KIND>[RESERVED(4)]<CLOSE STATUS><CLOSE MESSAGE>

Note

1. WebSocketClient reuse WebSocket close frame

Fields

We defined two encode format: Text and Binary, because WebSocket in browser transform string to Uint8Array is slow.

• LENGTH: the frame length, if transport protocol can split frames, it should not been set, else it must been set, varint format, from 1 byte to 4 bytes

• URL: the request url, starts with pathname, some internal query options starts with stmp_ as follow

  • stmp_version: the version of protocol
  • stmp_content_type: the default content type for the connection
  • stmp_server_latency: set SERVER LATENCY or not for response

  this is used for websocket client cannot set custom headers

• HEADER KEY/HEADER VALUE: this is same to HTTP, the difference is use \n to separate lines rather than \r\n

• HANDSHAKE STATUS: same to HTTP response status, two bytes BE in binary or 3 bytes base64 in text

• RESPONSE MESSAGE: an utf-8 encoded string
• RESERVED(n): reserve length n in bit

• KIND: the message kind, 3 bits in binary and 1 byte in text as follow:

  kind	binary	text
  Ping	0b000	p
  Request	0b001	q
  Push	0b010	n(notify)
  Response	0b011	s
  Close	0b100	c

• FLLOW: is following frame for other message or not, 1 bit in binary

  • text or WebSocket should not set this field, for it could framing internally.
  • This field only could be set for q/n/s messages.
  • If this field is set, the allowed following fields is MESSAGE ID and PAYLOAD, and both is required.

• FIN: the message has other frame or not, 1 bit in binary

  • text or WebSocket should not set this field, for it could framing internally.
  • This field only could be set for q/n/s messages.

• MESSAGE ID: the message id, from 0x0000 to 0xFFFF, 2 bytes in binary and 3 bytes base64 in text.

• ACTION: an utf-8 string, end with \n
• PAYLOAD: the raw payload data
• RESPONSE STATUS: the response status for request, same to HTTP, 2 bytes in binary and 3 bytes in text
• SERVER LATENCY: the server handle used time in milliseconds, 2 bytes in binary and 3 bytes in text
• CLOSE STATUS: the close status, same to WebSockets close code
• CLOSE MESSAGE: a utf-8 encoded string

LICENSE

The MIT License (MIT)

Copyright (c) 2017 acrazing

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.