{"_id":"@cs125/koa-easy-ws","_rev":"1-0939114c9d5df604ffc853d37ff1ac8d","name":"@cs125/koa-easy-ws","dist-tags":{"latest":"1.1.3"},"versions":{"1.1.3":{"name":"@cs125/koa-easy-ws","version":"1.1.3","description":"Simple Koa middleware for websocket handling","main":"index.js","scripts":{"test":"standard && mocha"},"repository":{"type":"git","url":"git+https://github.com/b3nsn0w/koa-easy-ws.git"},"keywords":["koa","websocket","ws"],"author":{"name":"Ben Snow","email":"balintbence97@gmail.com"},"license":"MIT","bugs":{"url":"https://github.com/b3nsn0w/koa-easy-ws/issues"},"homepage":"https://github.com/b3nsn0w/koa-easy-ws#readme","dependencies":{"debug":"^4.1.1","ws":"^7.2.3"},"devDependencies":{"chai":"^4.2.0","koa":"^2.11.0","koa-router":"^8.0.8","mocha":"^7.1.1","npm-check-updates":"^4.1.0","pre-commit":"^1.2.2","promise":"^8.1.0","request":"^2.88.2","request-promise":"^4.2.5","standard":"^14.3.3"},"pre-commit":["test"],"gitHead":"2d60f8cd1f26cd03535052c9e7ad28ee3d3308d5","_id":"@cs125/koa-easy-ws@1.1.3","_nodeVersion":"12.13.0","_npmVersion":"6.14.4","dist":{"integrity":"sha512-R16hd9gfsz4UVgKFiQ/RKEz6zHcnh7tyxjotf6ipUQENZNCe/RLoVEe48Ncr/P3Qw1o2tzStA1utyGbILFSJdA==","shasum":"7c8781d8add6839440d53ed3f9b521e60c34b79c","tarball":"https://registry.npmjs.org/@cs125/koa-easy-ws/-/koa-easy-ws-1.1.3.tgz","fileCount":9,"unpackedSize":15946,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJfMKg0CRA9TVsSAnZWagAA/6MQAJT3awX6jy6tSKZIvZ+X\n8lsi48PJx/y0r+zuNK1WR5RWoqis6XPcb3hTsRev9Vw4ClZihJEe9rV/qVKR\nJlrexL6xTbS+QMqx7oFSnjkmqI9E4CXXLLZN1QRl6rdaQBRVCTrDsIi184W4\nSyS0xMIgeCUYfOVN4E2nyux2UT51e8ATpMELLxf740jGWw8ppjUgWGNUi+3l\nV0nBy31rWMX8dus61cSrnrb9UBPSg0vMzipCrWDZAfHSOxMQTLMVtm0Ik1Tq\nSH8sIir4zwunp3SgNqAuoSW0/otVni50T51y+JvvT7710Elj7cfqMjMp1LG3\ndGwQZAaZPd2jvIpySXm1Z0Uvq2erQBz67SV8ViNC52cUMxobcN58ALxIHzpq\ns0B2N5yYoE+hkp1B96YiZbZG9rpBIJSWXXXS9ZGkJZz0fanoONCbo/oelcTM\nMIKYufRogSVoDWqs6CpHGJBWm7kA0g2p/GY2ClZHNnROOPU6SgdUYmAzhjyV\nDnjm5yM+yy9W9UlbI7luuQY79gB6uWr/LizwzValtrOfXTYt2c/sXvC3GuRC\nWGrb0g+NXcwOj1OS250WdMJTqEnIac72nWfUa1MgE4XYlkSwkOCFX0flvybC\nZqB8qZbgaZKm6w6gq9nNy6mKlebcNQCxRvusQcvWYb077ob7qdeWpKD5nRaW\nf4eX\r\n=ZNIa\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEQCIAIcVhZINI3KzdbFjdTa8qWRb6wBYCHUYVc73m+HecfdAiAioahMHVbNuaXSzw9kr3uHKliy8i59ZXrJiFCxIr3ceg=="}]},"maintainers":[{"name":"geoffrey.challen","email":"geoffrey.challen@gmail.com"}],"_npmUser":{"name":"geoffrey.challen","email":"geoffrey.challen@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/koa-easy-ws_1.1.3_1597024307447_0.16803676197593953"},"_hasShrinkwrap":false}},"time":{"created":"2020-08-10T01:51:47.356Z","1.1.3":"2020-08-10T01:51:47.593Z","modified":"2022-04-05T02:01:23.989Z"},"maintainers":[{"name":"geoffrey.challen","email":"geoffrey.challen@gmail.com"}],"description":"Simple Koa middleware for websocket handling","homepage":"https://github.com/b3nsn0w/koa-easy-ws#readme","keywords":["koa","websocket","ws"],"repository":{"type":"git","url":"git+https://github.com/b3nsn0w/koa-easy-ws.git"},"author":{"name":"Ben Snow","email":"balintbence97@gmail.com"},"bugs":{"url":"https://github.com/b3nsn0w/koa-easy-ws/issues"},"license":"MIT","readme":"Simple, easy to use, composable middleware for websocket handling in Koa\n\n# Usage\n\n```javascript\nconst Koa = require('koa')\nconst websocket = require('koa-easy-ws')\n\nconst app = new Koa()\n\napp.use(websocket())\napp.use(async (ctx, next) => {\n  // check if the current request is websocket\n  if (ctx.ws) {\n    const ws = await ctx.ws() // retrieve socket\n\n    // now you have a ws instance, you can use it as you see fit\n    return ws.send('hello there')\n  }\n  \n  // we're back to regular old http here\n  ctx.body = 'general kenobi'\n})\n```\n\nFirst, you need to pass the koa-easy-ws middleware before the one handling your request. Remember to call it as a function, `app.use(websocket())`, not `app.use(websocket)`. This sets up on-demand websocket handling for the rest of the middleware chain.\n\nThe middleware adds the `ctx.ws()` function whenever it detects an upgrade request, calling which handles the websocket and returns a [ws][ws] instance. If not called, regular Koa flow continues, likely resulting in a client-side error.\n\n# Features\n\n - No magic. This is a middleware, it doesn't turn your Koa app into a KoaMagicWebSocketServer. It knows its place.\n - Integrates [ws][ws], one of the fastest and most popular websocket libraries.\n - Full composability. Since this is just a middleware, it's not picky on what other libraries you use.\n - Minimal, unopinionated 40 SLOC codebase. Seriously, this readme alone contains more code than what's imported into your project. (sorry about the tests though)\n - Two dependencies only, and it's the ws library and [debug][debug] (because apparently logs are not a bad idea). No need for more clutter in your node_modules.\n\n# Examples and advanced configuration\n\nYou can easily compose koa-easy-ws with a routing library:\n\n```javascript\nconst Koa = require('koa')\nconst Router = require('koa-router')\nconst websocket = require('koa-easy-ws')\n\nconst app = new Koa()\nconst router = new Router()\n\napp\n  .use(websocket())\n  .use(router.routes())\n  .use(router.allowedMethods())\n\nrouter.get('/pow/obi', async (ctx, next) => {\n  if (ctx.ws) {\n    const ws = await ctx.ws()\n    ws.send('chancellor palpatine is evil')\n  }\n})\n\nrouter.get('/pow/ani', async (ctx, next) => {\n  if (ctx.ws) {\n    const ws = await ctx.ws()\n    ws.send('the jedi are evil')\n    ws.send('404')\n  }\n})\n```\n\nIf `ctx.ws()` isn't enough for you, the websocket server instance is also exposed:\n\n```javascript\nconst Koa = require('koa')\nconst websocket = require('koa-easy-ws')\n\nconst app = new Koa()\nconst websocketMiddleware = websocket()\nconst websocketServer = websocketMiddleware.server // this is where the fun begins\n\napp.use(websocketMiddleware) // we already have the instance here\n\n// <insert rest of the app>\n```\n\nThis gives you access to the [ws][ws] server object, allowing to pass down custom listeners, connection validators, etc.\n\nIn case `ctx.ws` conflicts with something else in your code, koa-easy-ws doesn't mind changing the property name, just pass it as a property. This also lets you use multiple websocket middlewares if you ever find a reason to do so:\n\n```javascript\nconst Koa = require('koa')\nconst websocket = require('koa-easy-ws')\n\nconst app = new Koa()\n\napp.use(websocket('sidious')) // we just renamed ctx.ws to ctx.sidious\napp.use(websocket('maul')) // attach another one for no good reason\n\napp.use(async (ctx, next) => {\n  // the first middleware detected an upgrade request\n  if (ctx.sidious) {\n    const socket = await ctx.sidious()\n    return socket.send('this is getting out of hand')\n  }\n\n  // the second middleware detected the same upgrade request\n  if (ctx.maul) {\n    const socket = await ctx.maul()\n    return socket.send('now there are two of them')\n  }\n})\n```\n\nNote: in this example `ctx.maul` is never used because there is no limit on the authority of `ctx.sidious`. However, if you define custom logic this technique could sort incoming requests to separate websocket servers.\n\nFrom here, the sky is the limit, unless you work for SpaceX.\n\n# Special usage for Node 9 or earlier\n\nNode's HTTP server doesn't send upgrade requests through the normal callback (and thus your Koa middleware chain) prior to version 10, preventing koa-easy-ws from handling them. Because of this, if you target Node 9 or earlier, you must pass your HTTP server to the middleware which handles the workaround:\n\n```javascript\nconst server = http.createServer(app.callback())\n\napp.use(websocket('ws', server))\n\n// alternatively, you can pass it as part of the options object:\napp.use(websocket('ws2', {\n  server: server\n}))\n\nserver.listen(process.env.PORT) // use this function instead of your app.listen() call\n```\n\nkoa-easy-ws then automatically feeds any upgrade request into your regular middleware chain. If you wish to opt out and do this yourself, use the `noServerWorkaround` option:\n\n```javascript\napp.use(websocket('ws', {\n  noServerWorkaround: true\n}))\n```\n\n# Contributing\n\nPull requests are welcome. As always, be respectful towards each other and maybe run or create tests, as appropriate. It's on `npm test`, as usual.\n\nkoa-easy-ws uses the MIT license. Was considering the WTFPL, but I like the \"no warranty\" clause.\n\n[ws]: https://github.com/websockets/ws\n[debug]: https://github.com/visionmedia/debug\n","readmeFilename":"README.md"}