{"id":24290154,"url":"https://github.com/clinth/remote","last_synced_at":"2025-12-04T14:10:09.002Z","repository":{"id":57102524,"uuid":"399055452","full_name":"ClintH/remote","owner":"ClintH","description":"A framework for super easy cross device communication","archived":false,"fork":false,"pushed_at":"2023-05-28T08:44:17.000Z","size":305,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-04-28T04:56:06.793Z","etag":null,"topics":["broadcastchannel","webrtc","websocket"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/ClintH.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":"2021-08-23T10:06:11.000Z","updated_at":"2024-08-26T23:36:04.843Z","dependencies_parsed_at":"2024-08-26T23:46:11.197Z","dependency_job_id":null,"html_url":"https://github.com/ClintH/remote","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClintH%2Fremote","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClintH%2Fremote/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClintH%2Fremote/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ClintH%2Fremote/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ClintH","download_url":"https://codeload.github.com/ClintH/remote/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242133430,"owners_count":20077095,"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":["broadcastchannel","webrtc","websocket"],"created_at":"2025-01-16T11:16:31.236Z","updated_at":"2025-12-04T14:10:08.967Z","avatar_url":"https://github.com/ClintH.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# remote\n\nRemote tries to simplify sending data to and from running sketches. It allows you to decouple sketches, thus making it easy to run components on different devices or simply in different windows.\n\nIt uses [WebRTC](https://developer.mozilla.org/en-US/docs/Web/API/RTCDataChannel), [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_client_applications) and [BroadcastChannel](https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API).\n\n## Example usage\n\nBy default, it does not use WebSockets or WebRTC, only BroadcastChannel for fast inter-window/inter-tab communication. This means messaging can only happen within the same computer.\n\nBroadcast a timestamp every 2 seconds to other sketches running locally:\n\n```js\nimport {Remote} from \"https://unpkg.com/@clinth/remote@latest/dist/index.mjs\";\n\nconst r = new Remote();\nsetInterval(() =\u003e {\n  r.broadcast({\n    timestamp: Date.now()\n  });\n}, 2000);\n```\n\nOr to send to a peer with the id '123-45':\n\n```js\nr.send({timestamp: Date.now()}, `123-45`);\n```\n\nReceive data and print to the console\n\n```js\nimport {Remote} from \"https://unpkg.com/@clinth/remote@latest/dist/index.mjs\";\n\nconst r = new Remote();\n\nr.onData = (d) =\u003e {\n  console.log(d);\n}\n```\n\n## Connecting further afield\n\nTo allow network connectivity, pass in the `allowNetwork` option when creating. This will allow you to send messages between different devices.\n\nYou may also want to specify the WebSocket URL via `websocket`. If you're running the provided server (see below), the address is `ws://127.0.0.1:8080/ws`. If you're running on Glitch, your address might be something like: `wss://MY-ZANY-PROJECT.glitch.me/ws`. Note the use of `wss` rather than `ws` when connecting over the wild internet.\n\n```js\nimport {Remote} from \"https://unpkg.com/@clinth/remote@latest/dist/index.mjs\";\n\nconst r = new Remote({\n  websocket: `ws://127.0.0.1:8080/ws`,\n  allowNetwork: true\n});\n```\n\nRemote will try to establish a WebRTC connection, advertised via the web socket server. Messages\nwhich are sent directly to a peer will use this means of transport. WebRTC can avoid a lot of the latency issues\nencountered if you're messaging via a publicly-hosted WebSocket server such as on Glitch.\n\n## Peer ids\n\nWhen starting, each instance creates a random id. You can get this with the id property:\n```js\nconst r = new Remote();\nr.id; // `1234-45`\n```\n\nIds are needed to direct a message to a specific peer (`r.send(msg, peerId)`), or if you want to do some kind of logic to process messages differently depending on what peer sent it. \n\nEach incoming message is marked with the property `_from` which can be used for this purpose:\n\n```js\nr.onData = (d) =\u003e {\n  if (d._from === `123-45`) {\n    // got it from a special friend\n  } else {\n    // got it from somewhere else\n  }\n}\n```\n\nIf a message was direct to a peer, it will also have a `_to` property. This can likewise be used behave differently if we got a generic broadcast or something just for us:\n\n```js\nconst ourId = r.id;\nr.onData = (d) =\u003e {\n  if (d._to === ourId) {\n    // Individual message\n  } else {\n    // Broadcast message\n  }\n}\n```\n\nYou can assign an id at start-up with the `peerId` parameter:\n\n```js\nconst r = new Remote({\n  peerId: `echo-six`,\n  websocket: `ws://127.0.0.1:8080/ws`,\n  allowNetwork: true\n});\n```\n\n## Web Socket server\n\nA naïve web socket server implementation is provided in the `server` folder. This can run on Glitch, or locally.\n\nTo run it locally:\n\n1. Have Node.js installed. \n2. Run `npm install` in the folder to install dependencies. \n\nOnce those steps are complete, it's just a matter of starting: `node server.js`\n\nIn all:\n\n```\ncd server\nnpm install\nnode server.js\n```\n\n## Security \u0026 privacy\n\n### Broadcast channel\n\nThe broadcast channel means of communication can be considered safe. Messages received are only from your own code, and the data you send won't leave your machine if `allowNetwork` is off (default).\n\n### Web sockets\n\nSending and receiving data via web sockets has some inherent risk because it travels via the internet. Using a `wss://` URL means that messages are encrypted between sender/receiver and the server, but this doesn't necessarily give much protection.\n\nIn principle, any web socket client can connect to your web socket server and receive or send data if they know its address. It is up to your server implementation to control which clients are allowed to connect, which messages are accepted for distribution, and which clients receive which messages.\n\nIn naïve implementations, the web socket server simply distributes received messages to all connected clients, and all connected clients are permitted to send messages. Turning off your server when not in use and using a random name for your server can reduce risk of misuse. \n\nRunning your web socket server on your own machine will also provide protection, because your operating system and network will not allow random traffic from the internet to reach your server (unless you have specifically configured it differently).\n\nIn short, be mindful of what you are sending when using a publicly-available server. When listening for data, in some cases you need to be mindful that the data may be coming from an untrusted source.\n\n### WebRTC\n\nWebRTC connections are facilitated by the web socket connection. This allows peers to exchange the handshake information required. Thus the possibility for peers to connect via WebRTC is contingent on their ability to connect to the WebSocket server.\n\n## Options\n\nWhen creating a new instance, options can be set to customise behaviour. All can be omitted by default.\n\n* websocket (string) URL for WebSocket server\n* peerId (string) Peer id\n* maintainLoopMs (number) How often to do housekeeping in milliseconds. Faster will catch disconnected states quicker, but higher CPU usage.\n* allowNetwork (boolean) If true, WebRTC \u0026 WebSockets will be attempted\n* debugMaintain (boolean) If true, spits out logging every time a housekeeping loop runs\n* defaultLog (string silent|verbose|error): Logging level ('error' by default)\n* log.ws / log.rtc / log.bc: Logging level for given sub-system\n\n## Diagnostics\n\nIf the following HTML element is in your page, it will be used to show some diagnostics info:\n\n```html\n\u003cdiv id=\"remote-status\"\u003e\u003c/div\u003e\n```\n\nClicking on it will dump out some information to the console for debugging connectivity.\n\n## Acknowledgements\n\nBundles:\n* Pedro Ladaria's [Reconnecting-Websocket](https://github.com/pladaria/reconnecting-websocket)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclinth%2Fremote","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclinth%2Fremote","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclinth%2Fremote/lists"}