Physical Connection Interface

https://www.npmjs.com/package/physical

Physical is an interface for a cross environment, cross system connection protocol that enables a democratization of internet resources by closing the gap between servers and clients in the connectivity department

Ensures you can negotiate connections and send data.

Reference Implementations

• https://www.npmjs.com/package/physical-node
• https://www.npmjs.com/package/physical-chrome

Interoperability of known implementations

|requester\responder|physical-node|physical-chrome| |---|---|---| |physical-node | WebSocket P/C | WebSocket P/C | |physical-chrome | WebSocket C/P | WebRTC |

Usage:

If you want to connect with another host, you must

1. create a new Physical object
2. call physical.request() to generate a serializable SYNQ object
3. pass the SYNQ object to the other host
4. wait for an ACK object, deserialize if necessary
5. call physical.open(ack)
6. wait for onOpen to fire.

If you want to let a host connect to you with a SYNQ object, you must

1. create a new Physical object
2. call physical.respond(synq) to generate a serializable ACK object
3. pass the ACK object to the other host
4. wait for onOpen to fire.

Methods:

request() : Promise<SYNQ>

generate a SYNQ request

SYNQ must contain a list of protocol names in SYNQ.supported, and the protocol offers in SYNQ.body in the same order.

respond(synq : SYNQ) : Promise<ACK>

respond to a SYNQ request

ACK must choose one compatible protocol and return a compliant response

open(ack : ACK) : void

unlock and open a physical connection

can only be called if request() has been called.

setOnOpen(f : ()=>void) : void

register a function to be called when the connection opens

send(message : string) : void

dispatch a message to the other host. throws exception if if the connection is not open

setOnMessage(f : (message : string) => void) : void

register a function to be called when a message comes through the connection this can be called multiple times if needed to update the onMessage function.

undefined behavior if not set.

close() : void

close the connection from your end

setOnClose(f : ()=>void) : void

register a function to be called when the connection closes