1
0
mirror of https://github.com/titanscouting/tra-analysis.git synced 2025-07-27 13:18:49 +00:00
Files
apps
data analysis
website
functions
node_modules
.bin
@firebase
@google-cloud
@grpc
@mrmlnc
@nodelib
@protobufjs
@types
accepts
acorn
acorn-es7-plugin
ajv
ansi-regex
arr-diff
arr-flatten
arr-union
array-filter
array-flatten
array-union
array-uniq
array-unique
arrify
ascli
asn1
assert-plus
assign-symbols
async
asynckit
atob
aws-sign2
aws4
axios
balanced-match
base
bcrypt-pbkdf
body-parser
brace-expansion
braces
buffer-equal-constant-time
buffer-from
bun
bytebuffer
bytes
cache-base
call-me-maybe
call-signature
camelcase
capture-stack-trace
caseless
class-utils
cliui
code-point-at
collection-visit
colour
combined-stream
component-emitter
compressible
concat-map
concat-stream
configstore
content-disposition
content-type
cookie
cookie-signature
copy-descriptor
core-js
core-util-is
cors
create-error-class
crypto-random-string
dashdash
debug
decamelize
decode-uri-component
deep-equal
define-properties
define-property
delayed-stream
depd
destroy
diff-match-patch
dir-glob
dom-storage
dot-prop
duplexify
eastasianwidth
ecc-jsbn
ecdsa-sig-formatter
ee-first
empower
empower-core
encodeurl
end-of-stream
ent
escape-html
espurify
estraverse
etag
expand-brackets
express
extend
extend-shallow
extglob
extsprintf
fast-deep-equal
fast-glob
fast-json-stable-stringify
faye-websocket
fill-range
finalhandler
firebase-admin
firebase-functions
follow-redirects
for-in
forever-agent
form-data
forwarded
fragment-cache
fresh
fs.realpath
functional-red-black-tree
gcp-metadata
gcs-resumable-upload
get-value
getpass
glob
glob-parent
glob-to-regexp
globby
google-auth-library
google-auto-auth
google-gax
google-p12-pem
google-proto-files
graceful-fs
grpc
gtoken
har-schema
har-validator
has-value
has-values
hash-stream-validation
http-errors
http-parser-js
http-signature
iconv-lite
ignore
imurmurhash
indexof
inflight
inherits
invert-kv
ipaddr.js
is
is-accessor-descriptor
is-buffer
is-data-descriptor
is-descriptor
is-extendable
is-extglob
is-fullwidth-code-point
is-glob
is-number
is-obj
is-plain-object
is-stream-ended
is-typedarray
is-windows
isarray
isobject
isstream
jsbn
json-schema
json-schema-traverse
json-stringify-safe
jsonwebtoken
jsprim
jwa
jws
kind-of
lcid
lodash
lodash.camelcase
lodash.clone
lodash.includes
lodash.isboolean
lodash.isinteger
lodash.isnumber
lodash.isplainobject
lodash.isstring
lodash.merge
lodash.once
log-driver
long
lru-cache
make-dir
map-cache
map-visit
media-typer
merge-descriptors
merge2
methmeth
methods
micromatch
mime
mime-db
mime-types
minimatch
mixin-deep
modelo
ms
nan
nanomatch
negotiator
node-forge
number-is-nan
oauth-sign
object-assign
object-copy
object-keys
object-visit
object.pick
on-finished
once
optjs
os-locale
parseurl
pascalcase
path-dirname
path-is-absolute
path-to-regexp
path-type
performance-now
pify
posix-character-classes
power-assert
power-assert-context-formatter
power-assert-context-reducer-ast
power-assert-context-traversal
power-assert-formatter
power-assert-renderer-assertion
power-assert-renderer-base
power-assert-renderer-comparison
power-assert-renderer-diagram
power-assert-renderer-file
power-assert-util-string-width
process-nextick-args
protobufjs
proxy-addr
pseudomap
psl
pump
pumpify
punycode
qs
range-parser
raw-body
readable-stream
regex-not
repeat-element
repeat-string
request
resolve-url
ret
retry-axios
retry-request
safe-buffer
safe-regex
safer-buffer
send
serve-static
set-value
setprototypeof
signal-exit
slash
snakeize
snapdragon
snapdragon-node
snapdragon-util
source-map
source-map-resolve
source-map-url
split-array-stream
split-string
sshpk
static-extend
statuses
stream-events
stream-shift
string-format-obj
string-width
string_decoder
stringifier
strip-ansi
stubs
through2
to-object-path
to-regex
to-regex-range
tough-cookie
traverse
tslib
tunnel-agent
tweetnacl
type-is
type-name
typedarray
union-value
unique-string
universal-deep-strict-equal
unpipe
unset-value
uri-js
urix
use
util-deprecate
utils-merge
uuid
vary
verror
websocket-driver
websocket-extensions
lib
CHANGELOG.md
LICENSE.md
README.md
package.json
window-size
wrap-ansi
wrappy
write-file-atomic
xdg-basedir
xmlhttprequest
xtend
y18n
yallist
yargs
index.js
package-lock.json
package.json
node_modules
public
.firebaserc
.gitignore
.runtimeconfig.json
firebase.json
firestore.indexes.json
firestore.rules
package-lock.json
.gitattributes
.gitignore
README.md
tra-analysis/website/functions/node_modules/websocket-extensions
2019-01-06 13:14:45 -06:00
..
2019-01-06 13:14:45 -06:00
2019-01-06 13:14:45 -06:00
2019-01-06 13:14:45 -06:00
2019-01-06 13:14:45 -06:00
2019-01-06 13:14:45 -06:00

websocket-extensions Build status

A minimal framework that supports the implementation of WebSocket extensions in a way that's decoupled from the main protocol. This library aims to allow a WebSocket extension to be written and used with any protocol library, by defining abstract representations of frames and messages that allow modules to co-operate.

websocket-extensions provides a container for registering extension plugins, and provides all the functions required to negotiate which extensions to use during a session via the Sec-WebSocket-Extensions header. By implementing the APIs defined in this document, an extension may be used by any WebSocket library based on this framework.

Installation

$ npm install websocket-extensions

Usage

There are two main audiences for this library: authors implementing the WebSocket protocol, and authors implementing extensions. End users of a WebSocket library or an extension should be able to use any extension by passing it as an argument to their chosen protocol library, without needing to know how either of them work, or how the websocket-extensions framework operates.

The library is designed with the aim that any protocol implementation and any extension can be used together, so long as they support the same abstract representation of frames and messages.

Data types

The APIs provided by the framework rely on two data types; extensions will expect to be given data and to be able to return data in these formats:

Frame

Frame is a structure representing a single WebSocket frame of any type. Frames are simple objects that must have at least the following properties, which represent the data encoded in the frame:

property description
final true if the FIN bit is set, false otherwise
rsv1 true if the RSV1 bit is set, false otherwise
rsv2 true if the RSV2 bit is set, false otherwise
rsv3 true if the RSV3 bit is set, false otherwise
opcode the numeric opcode (0, 1, 2, 8, 9, or 10) of the frame
masked true if the MASK bit is set, false otherwise
maskingKey a 4-byte Buffer if masked is true, otherwise null
payload a Buffer containing the (unmasked) application data

Message

A Message represents a complete application message, which can be formed from text, binary and continuation frames. It has the following properties:

property description
rsv1 true if the first frame of the message has the RSV1 bit set
rsv2 true if the first frame of the message has the RSV2 bit set
rsv3 true if the first frame of the message has the RSV3 bit set
opcode the numeric opcode (1 or 2) of the first frame of the message
data the concatenation of all the frame payloads in the message

For driver authors

A driver author is someone implementing the WebSocket protocol proper, and who wishes end users to be able to use WebSocket extensions with their library.

At the start of a WebSocket session, on both the client and the server side, they should begin by creating an extension container and adding whichever extensions they want to use.

var Extensions = require('websocket-extensions'),
    deflate    = require('permessage-deflate');

var exts = new Extensions();
exts.add(deflate);

In the following examples, exts refers to this Extensions instance.

Client sessions

Clients will use the methods generateOffer() and activate(header).

As part of the handshake process, the client must send a Sec-WebSocket-Extensions header to advertise that it supports the registered extensions. This header should be generated using:

request.headers['sec-websocket-extensions'] = exts.generateOffer();

This returns a string, for example "permessage-deflate; client_max_window_bits", that represents all the extensions the client is offering to use, and their parameters. This string may contain multiple offers for the same extension.

When the client receives the handshake response from the server, it should pass the incoming Sec-WebSocket-Extensions header in to exts to activate the extensions the server has accepted:

exts.activate(response.headers['sec-websocket-extensions']);

If the server has sent any extension responses that the client does not recognize, or are in conflict with one another for use of RSV bits, or that use invalid parameters for the named extensions, then exts.activate() will throw. In this event, the client driver should fail the connection with closing code 1010.

Server sessions

Servers will use the method generateResponse(header).

A server session needs to generate a Sec-WebSocket-Extensions header to send in its handshake response:

var clientOffer = request.headers['sec-websocket-extensions'],
    extResponse = exts.generateResponse(clientOffer);

response.headers['sec-websocket-extensions'] = extResponse;

Calling exts.generateResponse(header) activates those extensions the client has asked to use, if they are registered, asks each extension for a set of response parameters, and returns a string containing the response parameters for all accepted extensions.

In both directions

Both clients and servers will use the methods validFrameRsv(frame), processIncomingMessage(message) and processOutgoingMessage(message).

The WebSocket protocol requires that frames do not have any of the RSV bits set unless there is an extension in use that allows otherwise. When processing an incoming frame, sessions should pass a Frame object to:

exts.validFrameRsv(frame)

If this method returns false, the session should fail the WebSocket connection with closing code 1002.

To pass incoming messages through the extension stack, a session should construct a Message object according to the above datatype definitions, and call:

exts.processIncomingMessage(message, function(error, msg) {
  // hand the message off to the application
});

If any extensions fail to process the message, then the callback will yield an error and the session should fail the WebSocket connection with closing code 1010. If error is null, then msg should be passed on to the application.

To pass outgoing messages through the extension stack, a session should construct a Message as before, and call:

exts.processOutgoingMessage(message, function(error, msg) {
  // write message to the transport
});

If any extensions fail to process the message, then the callback will yield an error and the session should fail the WebSocket connection with closing code 1010. If error is null, then message should be converted into frames (with the message's rsv1, rsv2, rsv3 and opcode set on the first frame) and written to the transport.

At the end of the WebSocket session (either when the protocol is explicitly ended or the transport connection disconnects), the driver should call:

exts.close(function() {})

The callback is invoked when all extensions have finished processing any messages in the pipeline and it's safe to close the socket.

For extension authors

An extension author is someone implementing an extension that transforms WebSocket messages passing between the client and server. They would like to implement their extension once and have it work with any protocol library.

Extension authors will not install websocket-extensions or call it directly. Instead, they should implement the following API to allow their extension to plug into the websocket-extensions framework.

An Extension is any object that has the following properties:

property description
name a string containing the name of the extension as used in negotiation headers
type a string, must be "permessage"
rsv1 either true if the extension uses the RSV1 bit, false otherwise
rsv2 either true if the extension uses the RSV2 bit, false otherwise
rsv3 either true if the extension uses the RSV3 bit, false otherwise

It must also implement the following methods:

ext.createClientSession()

This returns a ClientSession, whose interface is defined below.

ext.createServerSession(offers)

This takes an array of offer params and returns a ServerSession, whose interface is defined below. For example, if the client handshake contains the offer header:

Sec-WebSocket-Extensions: permessage-deflate; server_no_context_takeover; server_max_window_bits=8, \
                          permessage-deflate; server_max_window_bits=15

then the permessage-deflate extension will receive the call:

ext.createServerSession([
  {server_no_context_takeover: true, server_max_window_bits: 8},
  {server_max_window_bits: 15}
]);

The extension must decide which set of parameters it wants to accept, if any, and return a ServerSession if it wants to accept the parameters and null otherwise.

ClientSession

A ClientSession is the type returned by ext.createClientSession(). It must implement the following methods, as well as the Session API listed below.

clientSession.generateOffer()
// e.g.  -> [
//            {server_no_context_takeover: true, server_max_window_bits: 8},
//            {server_max_window_bits: 15}
//          ]

This must return a set of parameters to include in the client's Sec-WebSocket-Extensions offer header. If the session wants to offer multiple configurations, it can return an array of sets of parameters as shown above.

clientSession.activate(params) // -> true

This must take a single set of parameters from the server's handshake response and use them to configure the client session. If the client accepts the given parameters, then this method must return true. If it returns any other value, the framework will interpret this as the client rejecting the response, and will throw.

ServerSession

A ServerSession is the type returned by ext.createServerSession(offers). It must implement the following methods, as well as the Session API listed below.

serverSession.generateResponse()
// e.g.  -> {server_max_window_bits: 8}

This returns the set of parameters the server session wants to send in its Sec-WebSocket-Extensions response header. Only one set of parameters is returned to the client per extension. Server sessions that would confict on their use of RSV bits are not activated.

Session

The Session API must be implemented by both client and server sessions. It contains two methods, processIncomingMessage(message) and processOutgoingMessage(message).

session.processIncomingMessage(message, function(error, msg) { ... })

The session must implement this method to take an incoming Message as defined above, transform it in any way it needs, then return it via the callback. If there is an error processing the message, this method should yield an error as the first argument.

session.processOutgoingMessage(message, function(error, msg) { ... })

The session must implement this method to take an outgoing Message as defined above, transform it in any way it needs, then return it via the callback. If there is an error processing the message, this method should yield an error as the first argument.

Note that both processIncomingMessage() and processOutgoingMessage() can perform their logic asynchronously, are allowed to process multiple messages concurrently, and are not required to complete working on messages in the same order the messages arrive. websocket-extensions will reorder messages as your extension emits them and will make sure every extension is given messages in the order they arrive from the driver. This allows extensions to maintain state that depends on the messages' wire order, for example keeping a DEFLATE compression context between messages.

session.close()

The framework will call this method when the WebSocket session ends, allowing the session to release any resources it's using.

Examples