http2Communicator

JSON and stream messaging over HTTP2.

How To Use

Installation

``shell
npm install @trevthedev/http2communicator
`

Basic Usage

On the Client

`javascript
const response = await client.ask({ whatever: 'question or resource request' })
`

On the Server

`javascript
server.on('question', async (serverResponse)=>{
serverResponse.reply({ response: 'what ever' })
})
`

More Advanced Example

$3

`javascript
import ServerNode from '@trevthedev/http2communicator'

const server = new ServerNode()

server.on('question', async (serverResponse) => {
console.log(LOG STEP 1: ${JSON.stringify(serverResponse.json)})

// handles any messages sent by client of type 'message' to this serverResponse
serverResponse.on('message', (msg) => console.log(LOG STEP 4: ${JSON.stringify(msg)}))

// sends 'hello' JSON message to client's question
serverResponse.say({ first: 'your', name: 'please', step: 2 }, 'hello')

// asks a question of client's question
const question = serverResponse.ask({
do: 'you', like: 'your', name: ['yes', 'no'], step: 3,
})

// handles any messages sent by client of type 'message' to this question
question.on('message', (msg) => {
console.log(LOG STEP 5: ${JSON.stringify(msg)})
question.say({ and: 'I', say: 'more', step: 6 }, 'more')
})

// waits for client to respond to question
console.log(LOG STEP 7: ${JSON.stringify(await question)})

// establishes a new stream from client to server (opposite of Push Stream)
// streams can also stream objects - known as Speaker
const incomingStream = await serverResponse.createListener('uploadFile', 'raw')
incomingStream.pipe(process.stdout)

// stream file to client - Push Stream
// streams can also stream objects - known as Speaker
const fileSpeaker = await serverResponse.createSpeaker('downloadFile', 'raw')
fs.createReadStream('package.json').pipe(fileSpeaker)

// after file has been streamed, reply to the original question
fileSpeaker.on('finish', () => serverResponse.reply({ my: 'name', is: 'server' }))
})

server.listen()
`

$3

`javascript
import ClientNode from '@trevthedev/http2communicator/client'

const client = new ClientNode()

// ask for something from the server (question)
const question = client.ask({ what: 'is', your: 'name', step: 1 })

// handles any messages sent by server of type 'hello' to this question
question.on('hello', (msg) => {
console.log(LOG STEP 2: ${JSON.stringify(msg)})

// sends message to server of type 'message' to this question
question.say({ i: 'say', stuff: true, step: 4 })
})

// handles any questions from the server to this question
// Response object is provided
question.on('question', (response) => {
console.log(LOG STEP 3: ${JSON.stringify(response.json)})

// handles any messages sent by server of type 'more' to this response
response.on('more', (msg) => {
console.log(LOG STEP 6: ${JSON.stringify(msg)})

// reply to servers question
response.reply({
answer: 'yes', i: 'like', my: 'name', step: 7,
})
})

// sends message to server of type 'message' to this response
response.say({ i: 'also', say: 'stuff', step: 5 })
})

// stream established by server.createListener
question.on('uploadFile', (stream) => {
fs.createReadStream('package.json').pipe(stream)
})

// stream established by server.createSpeaker
question.on('downloadFile', (stream) => {
stream.pipe(process.stdout)
});

(async () => {
// await response to question
const response = await question
console.log(LOG STEP 1 ANSWER: ${JSON.stringify(response)})
})()
`

API Reference

ServerNode

The host of the http2 server.

Instantiation:

`javascript
import ServerNode from '@TrevTheDev/http2Communicator'

const server = new ServerNode(http2Server, settings)
`

- http2Server \ optional http2Server - if one is not provide a new http2SecureServer instance is created based on settings.
- settings \ settings:
- serverPort: 8443,
- serverHostName: '127.0.0.1',
- serverPath: '/http2Communicator'
- listenerPath: '/http2Stream'
- keyFile: './dev certificate/selfsigned.key'
- certFile: './dev certificate/selfsigned.crt'
- certArgs: '/C=US/ST=Denial/L=Springfield/O=Dis/CN=www.example.com'
- log: true

#### serverNode.listen(port, hostname)

starts server listening

- port \ optional - see settings
- hostname \ optional - see settings serverHostName

#### serverNode.gracefulShutdown()

- returns \ Promise that gracefully closes all streams

ClientNode

A client the connects to a ServerNode.

Instantiation:

`javascript
import ClientNode from '@TrevTheDev/http2Communicator/client'

const client = new ClientNode(settings)
`

- settings \ settings:
- serverAddress: 'https://localhost:8443'
- http2ConnectionOptions: {
rejectUnauthorized: false,
enablePush: true,
}
- serverPath: '/http2Communicator'
- listenerPath: '/http2Stream'
- log: true

#### clientNode.ask(json)

Asks a new Question of the ServerNode

- json \ question to ask
- returns \ a Question promise that resolves after the response is received

#### clientNode.end()

- returns \ Promise that gracefully closes all streams

Question

Extends EventEmitter

Instantiation:

`javascript
clientNode.ask(Json)

serverResponse.ask(Json)
`

A Question is a request json Promise that awaits a response json. On await the Question is sent.

- returns \ a promise that resolves to the the response json

#### Properties

- id \ a Unique Identifier
- objectStream \ ObjectStream used for communications
- json \ Json of question
- response \ Response object if any
- speakers \ Array of active Speakers
- response \ if the Question is related to a particular Response - a "sub" question

#### Messages Handled

- reply on receipt this resolves the Question Promise. It will throw if there are any open Speakers
- cancelled on receipt this rejects the Question Promise with cancelled message. It will throw if there are any open Speakers
- question emits a question event with a new Response object
- listening emits a speakerType event with a Speaker |Stream object
- any messages not of the above type are emited as their message type

$3

Sends a json object of type via the ObjectStream. Say will only work after question has been sent to server via await.

ServerResponse

Extends Response

Instantiation:

`javascript
serverNode.on('question', (serverResponse) => {

})

`

#### Properties

- speakers \ array of connected Speakers|Streams
- Listeners \ array of connected listening Speakers|Streams

$3

Creates a new Speaker|Stream that the serverReponse can send either Objects on or anything else.

- speakerName \ event that will be emitted on the client
- speakerType \ speaker will be a Speaker if 'object' or a Stream if 'raw'
- optional \ if true then no promise is returned, rather returned Speaker will emit speakerType event on stream
- returns \Speaker |Speaker \> a promise that resolves to a Speaker or a Speaker

$3

Creates a new listening Speaker|Stream that the serverReponse can receive either Objects on or anything else.

- speakerName \ event that will be emitted on the client
- speakerType \ speaker will be a Speaker if 'object' or a Stream if 'raw'
- returns \Speaker |Promise->Stream\> a promise that resolves to a Speaker or a Stream

Response

Extends EventEmitter

Instantiation:

`javascript
question.on('question', (response) => {

})

`

#### Properties

- id \ a unique identifier
- objectStream \ ObjectStream used for communications
- json \ Json of received Question
- questions \ Array of Questions asked by this Response awaiting answers

#### Messages Handling

- any messages received are emited as their message type

$3

Sends json response to this Question and resolves promise. Type can also be cancelled to reject the Question. Throws if any Questions, Speakers or Listeners remain connected.

- json \ json response to question
- type \

Only one reply should be sent.

$3

Asks a new Question related to this Response

- json \ question to ask
- returns \ a Question promise that resolves after the response is received

$3

Sends a json object of type via the ObjectStream

ObjectStream

An object stream converts a stream of bytes into a stream of JSON objects. It emits a new event object for each object received

- stream \ stream to become object stream
- eventTarget \ optional target that will emit the object, end, finish, closed events

Speaker

Instantiation via serverResponse.createSpeaker and serverResponse.createListener

Sends JSON objects in one direction using an ObjectStream

$3

sends json over ObjectStream

$3

sends json over ObjectStream and ends ObjectStream`