{"id":21177513,"url":"https://github.com/sachskaylee/webtcp","last_synced_at":"2025-07-09T22:30:45.945Z","repository":{"id":129373597,"uuid":"138220771","full_name":"SachsKaylee/webtcp","owner":"SachsKaylee","description":"WebSocket/TCP bridge that allows browsers to interact with TCP servers. 📡","archived":false,"fork":false,"pushed_at":"2018-12-04T14:08:30.000Z","size":18,"stargazers_count":15,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-22T16:42:42.011Z","etag":null,"topics":["nodejs","server","tcp","websocket"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SachsKaylee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-21T20:54:32.000Z","updated_at":"2023-08-27T07:26:49.000Z","dependencies_parsed_at":"2023-06-14T16:30:14.110Z","dependency_job_id":null,"html_url":"https://github.com/SachsKaylee/webtcp","commit_stats":null,"previous_names":["patricksachs/webtcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/SachsKaylee/webtcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SachsKaylee%2Fwebtcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SachsKaylee%2Fwebtcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SachsKaylee%2Fwebtcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SachsKaylee%2Fwebtcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SachsKaylee","download_url":"https://codeload.github.com/SachsKaylee/webtcp/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SachsKaylee%2Fwebtcp/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264504573,"owners_count":23618825,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["nodejs","server","tcp","websocket"],"created_at":"2024-11-20T17:16:19.230Z","updated_at":"2025-07-09T22:30:45.940Z","avatar_url":"https://github.com/SachsKaylee.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebTCP 1.0.0 #\n\nInspired by the original WebTCP: [yankov/webtcp](https://github.com/yankov/webtcp)\n\nWebTCP allows users to create a raw TCP(With optional SSL support) socket using WebSockets.\n\nWhy a new library? The old library is abandoned, has too much functionality for being a raw TCP socket, and the code was hard to understand for me.\n\n## How does it work ##\n\nClient and server (bridge) communicate through a websocket connection. When the browser wants to create a TCP socket it sends a command to the bridge. The bridge creates a real TCP socket connection and maps all the events that happen on this socket to a client's socket object. For example, when data is received bridge will trigger a data event on according socket object on a browser side.\n\n## Why would anyone need that ##\n\nSometimes an API does not provide a way to communicate through HTTP or WebSockets, in which case you need to resort to raw TCP.\n\n## Can I use this in production? ##\n\n**Not without adjusting the configuration object.**\n\nWhy? This library allows users to leverage your server to create raw TCP sockets. They can literally do anything with that, all using your servers IP. \n\nYou would have to limit your users ability to connect to certain servers(`options.mayConnect`), properly encrypt the traffic both ways by using the `ssl` option, etc.\n\nThis library is not battle tested and is primarily used for prototyping by me, so be careful.\n\n## Installing ##\n\nAssuming you have `node.js`, `npm` and `git` installed:\n\n### Add as a dependency for using in your project ###\n\n```\nnpm install webtcp\n```\n\n### Clone the repository for testing/contributing ###\n\n**Clone the repo**  \n\n```\ngit clone https://github.com/PatrickSachs/webtcp\n```\n\n**Install dependencies**  \n\n```\ncd webtcp\nnpm install\n```\n\n**Run WebTCP example server**  \n\n```\nnpm run example\n```\n\nYour WebTCP server will now be hosted on localhost:9999.\n\n## How to use it ##\n\n### Client usage ###\n\nConnect to the bridge using a WebSocket. \n**Important:** Do not connect to the TCP server you want to communicate with here. You need to connect to the TCP bridge first. After connecting to the bridge you can then connect to the TCP server(as seen in the next step).\n\n```js\nconst socket = new WebSocket(\"localhost\", 9999);\n```\n\nThis WebSocket is now your TCP socket.\n\nBefore we can actually send data we need to connect to a TCP server:\n\n```js\nsocket.send(JSON.stringify({\n  type: \"connect\",\n  host: \"localhost\",\n  port: 8001\n}));  \n```\n\nAssuming everything went smooth the bridge will respond with\n\n```json\n{\n  \"type\": \"connect\"\n}\n```\nNow we are ready to send data:\n\n```js\n// Binary payload\nsocket.send(JSON.stringify({\n  type: \"data\",\n  payload: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]\n}));  \n// String payload\nsocket.send(JSON.stringify({\n  type: \"data\",\n  payload: \"Hello World\"\n}));  \n```\n\nOnce we are done, let's close the socket again:\n\n```js\nsocket.send(JSON.stringify({\n  type: \"close\"\n})); \n```\n\nThis will also close the websocket.\n\n## Events emitted by the bridge ##\n\n### connect ###\n\nOnce we have connected to the server the connect event occurs.\n\n```json\n{\n  \"type\": \"connect\"\n}\n```\n\n### data ###\n\nSent when the socket recceived data.\n\n```json\n{\n  \"type\": \"data\",\n  \"payload\": \"\u003cstring\u003e\"\n}\n```\n### end ###\n\nSent when the other end closed the socket by sending a FIN packet.\n\n```json\n{\n  \"type\": \"end\"\n}\n```\n\n### close ###\n\nSent when the socket is closed. If hadError is true an error event will be emitted aswell.\n\n```json\n{\n  \"type\": \"close\",\n  \"hadError\": \"\u003cboolean\u003e\"\n}\n```\n\n### error ###\n\nSent when an error occurred. This typically closes the socket.\n\n```json\n{\n  \"type\": \"error\",\n  \"error\": \"\u003cstring\u003e\"\n}\n```\n\n### timeout ###\n\nSent when the socket timed out due to inactivity.\n\n```json\n{\n  \"type\": \"timeout\"\n}\n```\n\n## Events handled by the bridge ##\n\n### connect ###\n\nUsed to connect to a TCP server.\n\n```json\n{\n  \"type\": \"connect\",\n  \"host\": \"\u003cstring\u003e\",\n  \"port\": \"\u003cnumber\u003e\",\n  \"encoding\": \"\u003cstring\u003e\",\n  \"timeout\": \"\u003cnumber\u003e\",\n  \"noDelay\": \"\u003cboolean\u003e\",\n  \"keepAlive\": \"\u003cboolean\u003e\",\n  \"initialDelay\": \"\u003cnumber\u003e\",\n  \"ssl\": \"\u003cboolean\u003e\"\n}\n```\n\n### close ###\n\nCloses the TCP Socket \u0026 WebSocket.\n\n```json\n{\n  \"type\": \"close\"\n}\n```\n\n### data ###\n\nSends data. The payload can either be a string on an array of bytes(=numbers).\n\n```json\n{\n  \"type\": \"data\",\n  \"payload\": \"\u003cstring | number[]\u003e\"\n}\n```\n\n## Manually creating a server ##\n\nThis is pretty much a copy of the example included under `/examples/server.js`, but it's always nice to see a code example.\n\nAs you can see WebTCP integrates seamlessly into express using the `express-ws` library. You can of course roll your own solution, which would require you to adjust the `createConnection` function passed in the options to use your WebSocket API.\n\n```js\nconst webtcp = require(\"webtcp\");\nconst express = require(\"express\");\nconst enableWebsockets = require(\"express-ws\");\n\nconst PORT = 9999;\n\nconst app = express();\nenableWebsockets(app);\n\n// All options are optional. The following values are the default ones.\napp.ws(\"/\", webtcp({\n  // The options for this webtcp server instance\n  debug: false,\n  mayConnect: ({host, port}) =\u003e true,\n  // Creates the connection/session object if you are using a non-default WebSocket implementation.\n  createConnection: (ws, req) =\u003e ({\n    // Sends a JSON object over the WebSocket.\n    send: data =\u003e ws.send(JSON.stringify(data)),\n    // Checks if the socket is open. If this returns true, the server assumes that calling send will work.\n    isOpen: () =\u003e ws.readyState === READY_STATE.OPEN,\n    // Placeholder for the TCP socket. Simply set this to null unless you need to get really fancy.\n    socket: null\n  }),\n  // The default options for the TCP socket\n  defaultTcpOptions: {\n    host: \"localhost\",\n    port: 9998,\n    ssl: false,\n    encoding: \"utf8\",\n    timeout: 0,\n    noDelay: false,\n    keepAlive: false,\n    initialDelay: 0\n  }\n});\napp.listen(PORT, () =\u003e console.log(`[webtcp] Running on port ${PORT}!`));\n```\n\n## Contributing ##\n\nAlways welcome! Feel free to open issues and PRs as you wish, then we can talk about possible additions/fixes/changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsachskaylee%2Fwebtcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsachskaylee%2Fwebtcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsachskaylee%2Fwebtcp/lists"}