{"_id":"hyco-websocket","_rev":"89-9fc39813a467996a8967294ec8dd018f","name":"hyco-websocket","dist-tags":{"latest":"1.0.5"},"versions":{"1.0.0":{"name":"hyco-websocket","version":"1.0.0","keywords":["websocket","websockets","socket","networking","comet","push","RFC-6455","realtime","server","client"],"author":"","license":"Apache-2.0","_id":"hyco-websocket@1.0.0","maintainers":[{"name":"microsoft","email":"npmjs@microsoft.com"}],"homepage":"https://azure.com","bugs":{"url":"https://github.com/clemensv/azure-relay-hybridconnections/issues"},"dist":{"shasum":"eeaf8c40041f7148838a10b8863c5f7cc1491cc1","tarball":"https://registry.npmjs.org/hyco-websocket/-/hyco-websocket-1.0.0.tgz","integrity":"sha512-Ti7UV4xu4eA8hL8wP1TqGm7vVwoiEaiyJzkivwKMAubbcGs6AHau4zkXi/m0tB600nlfbucs4LBTtkfSmL0TKA==","signatures":[{"sig":"MEQCIHbnJHsJW1wu4CI9MPAgir61v1+KJv5ZOaZQF6WLdQ4cAiAuLpJW1s3ncet4snF2yoG5wLOuHSzDIdu4bsbwVfDtag==","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"index","_from":".","config":{"verbose":false},"_shasum":"eeaf8c40041f7148838a10b8863c5f7cc1491cc1","engines":{"node":">=0.8.0"},"scripts":{},"_npmUser":{"name":"microsoft","email":"npmjs@microsoft.com"},"repository":{"url":"git+https://github.com/clemensv/azure-relay-hybridconnections.git","type":"git"},"_npmVersion":"3.9.5","description":"This Node package for Azure Relay Hybrid Connections is built on and extends the \r ['websocket'](https://www.npmjs.com/package/websocket) NPM package. This package \r re-exports all exports of that base package and adds new exports that enable \r integratio","directories":{"lib":"./lib"},"_nodeVersion":"6.2.2","dependencies":{"crypto":"latest","moment":"latest","websocket":"latest"},"devDependencies":{},"_npmOperationalInternal":{"tmp":"tmp/hyco-websocket-1.0.0.tgz_1478014268209_0.12508383835665882","host":"packages-12-west.internal.npmjs.com"}},"1.0.3":{"name":"hyco-websocket","version":"1.0.3","keywords":["websocket","websockets","socket","networking","comet","push","RFC-6455","realtime","server","client"],"author":{"name":"Microsoft Corporation"},"license":"Apache-2.0","_id":"hyco-websocket@1.0.3","maintainers":[{"name":"jtaubensee","email":"jtaubensee@outlook.com"},{"name":"microsoft","email":"npmjs@microsoft.com"}],"homepage":"https://azure.com","bugs":{"url":"https://github.com/Azure/azure-relay-node/issues"},"dist":{"shasum":"558e44290d73fafcb85a4addf0e0d2f98dd23b86","tarball":"https://registry.npmjs.org/hyco-websocket/-/hyco-websocket-1.0.3.tgz","integrity":"sha512-5o2UlYVbdM49fabGEwYESasMJ6VPT0m0BxYLts/PCDVyEbyZWN1IaGHE4rZKg0FrPyk5VNODWHj9MHQ0jXmhWg==","signatures":[{"sig":"MEUCIQDnhgWDqGWDE5i7VAWnaZtb9mUKE/Q1KzXgl2U5dR+cUgIgWxIskajAX58h8kA5fsBJ2Tb0E70qAM1iPe7Ix5tgFoA=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"index.js","_from":".","config":{"verbose":false},"_shasum":"558e44290d73fafcb85a4addf0e0d2f98dd23b86","engines":{"node":">=0.8.0"},"scripts":{},"_npmUser":{"name":"microsoft","email":"npmjs@microsoft.com"},"repository":{"url":"git+https://github.com/Azure/azure-relay-node.git","type":"git"},"_npmVersion":"3.9.5","description":"This Node package for Azure Relay Hybrid Connections is built on and extends the \r ['websocket'](https://www.npmjs.com/package/websocket) NPM package. This package \r re-exports all exports of that base package and adds new exports that enable \r integratio","directories":{"lib":"./lib"},"_nodeVersion":"6.2.2","dependencies":{"crypto":"latest","moment":"latest","websocket":"latest"},"_npmOperationalInternal":{"tmp":"tmp/hyco-websocket-1.0.3.tgz_1478021272440_0.859805541113019","host":"packages-18-east.internal.npmjs.com"}},"1.0.4":{"name":"hyco-websocket","version":"1.0.4","keywords":["websocket","websockets","socket","networking","comet","push","RFC-6455","realtime","server","client"],"author":{"name":"Microsoft Corporation"},"license":"Apache-2.0","_id":"hyco-websocket@1.0.4","maintainers":[{"name":"jtaubensee","email":"jtaubensee@outlook.com"},{"name":"microsoft","email":"npmjs@microsoft.com"}],"homepage":"https://azure.com","bugs":{"url":"https://github.com/Azure/azure-relay-node/issues"},"dist":{"shasum":"1e6f0c9b4215ce93241e77e450c0306bbe7fcd4d","tarball":"https://registry.npmjs.org/hyco-websocket/-/hyco-websocket-1.0.4.tgz","integrity":"sha512-enj50M+pFPG2POSVW2Vjv/324QEMGW7ynE0efncq3J2HWTbr6XfIdUG/BPmxo1Eq04eHJpZSsMz/knUJh3L1CA==","signatures":[{"sig":"MEYCIQCsddoz2z6953qF0HVCHxqXoSUM7Vi1/S5ZZtGcZBea5gIhAPlDwm71WQiglFWHQIq3mBeYbS3loZ2GzMP0Vc40yWKi","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"index.js","_from":".","config":{"verbose":false},"_shasum":"1e6f0c9b4215ce93241e77e450c0306bbe7fcd4d","engines":{"node":">=0.8.0"},"scripts":{},"_npmUser":{"name":"jtaubensee","email":"jtaubensee@outlook.com"},"repository":{"url":"git+https://github.com/Azure/azure-relay-node.git","type":"git"},"_npmVersion":"3.10.8","description":"This Node package for Azure Relay Hybrid Connections is built on and extends the \r ['websocket'](https://www.npmjs.com/package/websocket) NPM package. This package \r re-exports all exports of that base package and adds new exports that enable \r integratio","directories":{"lib":"./lib"},"_nodeVersion":"7.0.0","dependencies":{"url":"latest","crypto":"latest","events":"latest","moment":"latest","wait.for":"latest","websocket":"latest","querystring":"latest"},"_npmOperationalInternal":{"tmp":"tmp/hyco-websocket-1.0.4.tgz_1480524692789_0.9032827231567353","host":"packages-12-west.internal.npmjs.com"}},"1.0.5":{"name":"hyco-websocket","version":"1.0.5","keywords":["websocket","websockets","socket","networking","comet","push","RFC-6455","realtime","server","client"],"author":{"name":"Microsoft Corporation"},"license":"MIT","_id":"hyco-websocket@1.0.5","maintainers":[{"name":"jtaubensee","email":"jtaubensee@outlook.com"},{"name":"microsoft","email":"npmjs@microsoft.com"}],"homepage":"https://docs.microsoft.com/en-us/azure/service-bus-relay/","bugs":{"url":"https://github.com/Azure/azure-relay-node/issues"},"dist":{"shasum":"ffd99b28aedea0f694c5d0c44431a429113705ac","tarball":"https://registry.npmjs.org/hyco-websocket/-/hyco-websocket-1.0.5.tgz","integrity":"sha512-3/EvQXjfCzMQYg9M3eiiAveEs1HIH1ke2Xcyw/rtPEchWK8SSd0N8XbDwvpGxeXtf6Oyqpwuv0Ehj7YRwIrClQ==","signatures":[{"sig":"MEUCIQCtVuOjP0LxQvAH+mY+oG84WdoewnDF+0FfGSd/+4p62wIgdXAxHnvVpCiZhXPsHETbFRk3HL0pSV3AJA4+wri0yGo=","keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA"}]},"main":"index.js","_from":".","config":{"verbose":false},"_shasum":"ffd99b28aedea0f694c5d0c44431a429113705ac","engines":{"node":">=0.8.0"},"scripts":{},"_npmUser":{"name":"jtaubensee","email":"jtaubensee@outlook.com"},"repository":{"url":"git+https://github.com/Azure/azure-relay-node.git","type":"git"},"_npmVersion":"3.10.8","description":"This Node package for Azure Relay Hybrid Connections is built on and extends the \r ['websocket'](https://www.npmjs.com/package/websocket) NPM package. This package \r re-exports all exports of that base package and adds new exports that enable \r integratio","directories":{"lib":"./lib"},"_nodeVersion":"7.0.0","dependencies":{"url":"latest","crypto":"latest","events":"latest","moment":"latest","websocket":"latest","querystring":"latest"},"_npmOperationalInternal":{"tmp":"tmp/hyco-websocket-1.0.5.tgz_1490387217344_0.953561901114881","host":"packages-12-west.internal.npmjs.com"}}},"time":{"created":"2016-11-01T15:31:10.200Z","modified":"2026-07-16T15:48:32.319Z","1.0.0":"2016-11-01T15:31:10.200Z","1.0.3":"2016-11-01T17:27:54.417Z","1.0.4":"2016-11-30T16:51:33.011Z","1.0.5":"2017-03-24T20:26:59.426Z"},"bugs":{"url":"https://github.com/Azure/azure-relay-node/issues"},"author":{"name":"Microsoft Corporation"},"license":"MIT","homepage":"https://docs.microsoft.com/en-us/azure/service-bus-relay/","keywords":["websocket","websockets","socket","networking","comet","push","RFC-6455","realtime","server","client"],"repository":{"url":"git+https://github.com/Azure/azure-relay-node.git","type":"git"},"description":"This Node package for Azure Relay Hybrid Connections is built on and extends the \r ['websocket'](https://www.npmjs.com/package/websocket) NPM package. This package \r re-exports all exports of that base package and adds new exports that enable \r integratio","maintainers":[{"email":"npmjs@microsoft.com","name":"microsoft1es"},{"email":"microsoft-oss-publishing@microsoft.com","name":"microsoft-oss-releases"},{"email":"jtaubensee@outlook.com","name":"jtaubensee"}],"readme":"# The 'hyco-websocket' Package for Azure Relay Hybrid Connections \r\n\r\n## Overview\r\n\r\nThis Node package for Azure Relay Hybrid Connections is built on and extends the \r\n['websocket'](https://www.npmjs.com/package/websocket) NPM package. This package \r\nre-exports all exports of that base package and adds new exports that enable \r\nintegration with the Azure Relay service's Hybrid Connections feature. \r\n\r\nExisting applications that `require('websocket')` can use this package instead \r\nwith `require('hyco-websocket')` , which also enables hybrid scenarios where an \r\napplication can listen for WebSocket connections locally from \"inside the firewall\"\r\nand via Relay Hybrid Connections all at the same time.\r\n  \r\n## Documentation\r\n\r\nThe API is [generally documented in the main 'websocket' package](https://github.com/theturtle32/WebSocket-Node/blob/master/docs/index.md)\r\nand this document describes how this package differs from that baseline. \r\n\r\nThe key differences between the base package and this 'hyco-websocket' is that it adds \r\na new server class, that is exported via `require('hyco-websocket').relayedServer`,\r\nand a few helper methods.\r\n\r\n### Package Helper methods\r\n\r\nThere are three new utility methods available on the package export that can be \r\nreferenced like this:\r\n\r\n``` JavaScript\r\nconst WebSocket = require('hyco-websocket');\r\n\r\nvar listenUri = WebSocket.createRelayListenUri('namespace.servicebus.windows.net', 'path');\r\nlistenUri = WebSocket.appendRelayToken(listenUri, 'ruleName', '...key...')\r\n...\r\n\r\n```\r\n\r\nThe helper methods are for use with this package, but might be also be used by a Node server \r\nfor enabling web or device clients to create listeners or senders by handing them URIs that\r\nalready embed short-lived tokens and that can be used with common WebSocket stacks that do \r\nnot support setting HTTP headers for the WebSocket handshake. Embedding authorization tokens\r\ninto the URI is primarily supported for those library-external usage scenarios. \r\n\r\n#### createRelayListenUri\r\n\r\n``` JavaScript\r\nvar uri = WebSocket.createRelayListenUri([namespaceName], [path], [[token]], [[id]])\r\n```\r\n\r\nCreates a valid Azure Relay Hybrid Connection listener URI for the given namespace and path. This \r\nURI can then be used with the relayed version of the WebSocketServer class.\r\n\r\n- **namespaceName** (required) - the domain-qualified name of the Azure Relay namespace to use\r\n- **path** (required) - the name of an existing Azure Relay Hybrid Connection in that namespace\r\n- **token** (optional) - a previously issued Relay access token that shall be embedded in\r\n                         the listener URI (see below)\r\n- **id** (optional) - a tracking identifier that allows end-to-end diagnostics tracking of requests\r\n\r\nThe **token** value is optional and should only be used when it is not possible to send HTTP \r\nheaders along with the WebSocket handshake as it is the case with the W3C WebSocket stack.                  \r\n\r\n\r\n#### createRelaySendUri \r\n``` JavaScript\r\nvar uri = WebSocket.createRelaySendUri([namespaceName], [path], [[token]], [[id]])\r\n```\r\n\r\nCreates a valid Azure Relay Hybrid Connection send URI for the given namespace and path. This \r\nURI can be used with any WebSocket client.\r\n\r\n- **namespaceName** (required) - the domain-qualified name of the Azure Relay namespace to use\r\n- **path** (required) - the name of an existing Azure Relay Hybrid Connection in that namespace\r\n- **token** (optional) - a previously issued Relay access token that shall be embedded in\r\n                         the send URI (see below)\r\n- **id** (optional) - a tracking identifier that allows end-to-end diagnostics tracking of requests\r\n\r\nThe **token** value is optional and should only be used when it is not possible to send HTTP \r\nheaders along with the WebSocket handshake as it is the case with the W3C WebSocket stack.                   \r\n\r\n\r\n#### createRelayToken \r\n``` JavaScript\r\nvar token = WebSocket.createRelayToken([uri], [ruleName], [key], [[expirationSeconds]])\r\n```\r\n\r\nCreates an Azure Relay Shared Access Signature (SAS) token for the given target URI, SAS rule, \r\nand SAS rule key that is valid until the given expiration instant (UNIX epoch) or for an \r\nhour from the current instant if the expiry argunent is omitted. \r\n\r\n- **uri** (required) - the URI for which the token is to be issued. The URI will be normalized to \r\n                       using the http scheme and query string information will be stripped.\r\n- **ruleName** (required) - SAS rule name either for the entity represented by the given URI or \r\n                            for the namespace represented by the URI host-portion.\r\n- **key** (required) - valid key for the SAS rule.\r\n- **expirationSeconds** (optional) - the number of seconds until the generated token should expire. \r\n                            The default is 1 hour (3600) if not specified.\r\n\r\nThe issued token will confer the rights associated with the chosen SAS rule for the chosen duration.\r\n\r\n#### appendRelayToken\r\n``` JavaScript\r\nvar uri = WebSocket.appendRelayToken([uri], [ruleName], [key], [[expirationSeconds]])\r\n```\r\n\r\nThis method is functionally equivalent to the **createRelayToken** method above, but\r\nreturns the token correctly appended to the input URI.\r\n\r\n### HybridConnectionsWebSocketServer\r\n\r\nThe `HybridConnectionsWebSocketServer` class is an alternative to the `WebSocketServer`\r\nclass that does not listen on the local network, but delegates listening to the Azure Relay.\r\n\r\nThe two classes are largely contract compatible, meaning that an existing application using \r\nthe `WebSocketServer` class can be changed to use the relayed version quite easily. The \r\nmain differences are the constructor and an unfortunately required behavioral change for when \r\nexplicit control of accepting incoming WebSockets is required.\r\n\r\nThe `HybridConnectionsWebSocketServer` does not support the `mount()` and `unmount()` methods. \r\nThe server starts automatically after construction.  \r\n\r\n#### Constructor  \r\n\r\n``` JavaScript \r\nvar WebSocket = require('hyco-websocket');\r\nvar HybridConnectionsWebSocketServer = WebSocket.relayedServer;\r\n\r\nvar wss = new HybridConnectionsWebSocketServer(\r\n    {\r\n        server : WebSocket.createRelayListenUri(ns, path),\r\n        token: function() { return WebSocket.createRelayToken('http://' + ns, keyrule, key); },\r\n        autoAcceptConnections : true\r\n    });\r\n```\r\n\r\nThe `HybridConnectionsWebSocketServer` constructor supports a different set of arguments than the \r\n`WebSocketServer` since it is neither a standalone listener nor embeddable into an existing HTTP\r\nlistener framework. There are also fewer options available since the WebSocket management is \r\nlargely delegated to the Relay service.\r\n\r\nConstructor arguments:\r\n\r\n- **server** (required) - the fully qualified URI for a Hybrid Connection name on which to listen, usually\r\n                          constructed with the WebSocket.createRelayListenUri() helper.\r\n- **token** (required) - this argument *either* holds a previously issued token string *or* a callback\r\n                         function that can be called to obtain such a token string. The callback option\r\n                         is preferred as it allows token renewal.\r\n- **autoAcceptConnections** (optional, defaults to *false*) - determines whether connections should be \r\n                         automatically accepted, independent of the sub-protocol and extensions. \r\n\r\n#### Events\r\n\r\nJust as with the stock WebSocketServer, HybridConnectionsWebSocketServer instances emit three Events\r\nthat allow you to handle incoming requests, establish connections, and detect when a connection \r\nhas been closed.\r\n\r\n##### request\r\n``` JavaScript\r\nfunction(webSocketRequest)\r\n```\r\n\r\nIf autoAcceptConnections is set to false, a request event will be emitted by the server whenever \r\na new WebSocket request is made. You should inspect the requested protocols and the user's origin \r\nto verify the connection, and then accept or reject it by calling `webSocketRequest.accept('chosen-protocol', 'accepted-origin', cb)` or `webSocketRequest.reject(cb)`. \r\n\r\n> **ATTENTION! CHANGE IN BEHAVIOR.** \r\n> The accept() and reject() methods of [WebSocketRequest](https://github.com/theturtle32/WebSocket-Node/blob/master/docs/WebSocketRequest.md) \r\n> in the base library are synchronous. The method accept() immediately returns the `WebSocketConnection`.\r\n> With the Relay, accepting the connection requires a network activity, which means the operation must\r\n> be carried out asynchronously. See details below in `HybridConnectionsWebSocketRequest`.\r\n\r\n##### connect\r\n``` JavaScript\r\nfunction(webSocketConnection)\r\n```\r\n\r\nEmitted whenever a new WebSocket connection is accepted.\r\n\r\n##### close\r\n``` JavaScript\r\nfunction(webSocketConnection, closeReason, description)\r\n```\r\n\r\nWhenever a connection is closed for any reason, the HybridConnectionsWebSocketServer instance will emit a close event,\r\npassing a reference to the WebSocketConnection instance that was closed. closeReason is the numeric \r\nreason status code for the connection closure, and description is a textual description of the close \r\nreason, if available.  \r\n\r\n### HybridConnectionsWebSocketRequest\r\n\r\nThe request object is a variation of the [WebSocketRequest](https://github.com/theturtle32/WebSocket-Node/blob/master/docs/WebSocketRequest.md)\r\nobject that is made available through the request event callback on the server object when `autoAcceptConnections` is set to false.\r\n\r\nThe object is functionally equivalent and provides the same information properties as the \r\nbase object. The signatures of the `accept` and `reject` methods differ:\r\n\r\n#### Methods\r\n\r\nThe following two methods differ from the stock request object in being asynchronous: \r\n\r\n##### accept\r\n``` JavaScript\r\naccept(acceptedProtocol, allowedOrigin, cookies, callback)\r\n```\r\n\r\nReturns: nothing\r\n\r\nAfter inspecting the HybridConnectionsWebSocketRequest's properties, call this function on the request object to \r\naccept the connection. If you don't have a particular subprotocol you wish to speak, you may \r\npass null for the acceptedProtocol parameter. Note that the acceptedProtocol parameter is \r\ncase-insensitive, and you must either pass a value that was originally requested by the client or \r\nnull. For browser clients (in which the origin property would be non-null) you must pass that \r\nuser's origin as the allowedOrigin parameter to confirm that you wish to accept connections \r\nfrom the given origin. \r\n\r\nThe callback is invoked with the established WebSocketConnection instance that can be used \r\nto communicate with the connected client.\r\n\r\n##### reject\r\n``` JavaScript\r\nreject([httpStatus], [reason], cb)\r\n```\r\n\r\nIf you decide to reject the connection, you must call reject. You may optionally pass in an \r\nHTTP Status code (such as 404) and a textual description that will be sent to the client. \r\nThe connection will then be closed.\r\n\r\nThe callback is invoked, without arguments, when the rejection is complete.\r\n","readmeFilename":"README.md"}