├── .dockerignore ├── .github ├── release-drafter.yml └── workflows │ ├── ci.yaml │ └── release-please.yml ├── .gitignore ├── .gitmodules ├── .npmrc ├── Dockerfile ├── LICENSE ├── Makefile ├── README.md ├── client-web ├── .gitignore ├── index.html ├── package.json ├── proto │ └── sfu.proto ├── public │ └── vite.svg ├── src │ ├── component.ts │ ├── index.ts │ ├── lib │ │ ├── core.ts │ │ ├── index.ts │ │ └── sfu.ts │ └── vite-env.d.ts ├── tsconfig.json └── vite.config.ts ├── demo-cdn ├── README.md ├── index.html ├── main.js └── package.json ├── demo-react ├── .gitignore ├── README.md ├── eslint.config.js ├── functions │ └── auth.ts ├── index.html ├── package.json ├── public │ └── vite.svg ├── src │ ├── App.tsx │ ├── main.tsx │ ├── util.ts │ └── vite-env.d.ts ├── tsconfig.app.json ├── tsconfig.json ├── tsconfig.node.json ├── vite.config.ts └── wrangler.toml ├── demo-server ├── README.md ├── index.d.ts ├── index.js └── package.json ├── package-lock.json ├── package.json ├── peer ├── .gitignore ├── CONTRIBUTING.md ├── Makefile ├── README.md ├── bump.bash ├── generate.bash ├── index.html ├── jsr.json ├── main.ts ├── package.json ├── scripts │ └── patch.cjs ├── src │ ├── analytics.ts │ ├── index.ts │ ├── logger.test.ts │ ├── logger.ts │ ├── peer.ts │ ├── session.ts │ ├── signaling.client.ts │ ├── signaling.ts │ ├── store.ts │ ├── transport.ts │ ├── util.ts │ └── vite-env.d.ts ├── tsconfig.json ├── vite.config.ts └── vitest.config.ts ├── playwright.config.ts └── tests └── demo-react.spec.ts /.dockerignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | -------------------------------------------------------------------------------- /.github/release-drafter.yml: -------------------------------------------------------------------------------- 1 | template: | 2 | ## What’s Changed 3 | 4 | $CHANGES 5 | -------------------------------------------------------------------------------- /.github/workflows/ci.yaml: -------------------------------------------------------------------------------- 1 | name: CI 2 | 3 | on: 4 | push: 5 | branches: ['main'] 6 | tags: 7 | - "v*" 8 | pull_request: 9 | branches: ['main'] 10 | 11 | schedule: 12 | - cron: "0 * * * *" 13 | 14 | workflow_dispatch: 15 | inputs: 16 | tag: 17 | description: 'Tag to release (e.g., v1.2.3)' 18 | required: false 19 | default: '' 20 | 21 | env: 22 | REGISTRY: ghcr.io 23 | IMAGE_NAME: ${{ github.repository }} 24 | 25 | jobs: 26 | test: 27 | timeout-minutes: 60 28 | runs-on: ubuntu-24.04 29 | steps: 30 | - uses: actions/checkout@v4 31 | with: 32 | ref: ${{ github.event.inputs.tag || github.ref }} 33 | - uses: actions/setup-node@v4 34 | with: 35 | node-version: lts/* 36 | - name: Install dependencies 37 | run: npm ci 38 | - name: Install Playwright Browsers 39 | run: npx playwright install --with-deps 40 | - name: Run tests 41 | run: make test 42 | env: 43 | PULSEBEAM_API_KEY: ${{ secrets.PULSEBEAM_API_KEY }} 44 | PULSEBEAM_API_SECRET: ${{ secrets.PULSEBEAM_API_SECRET }} 45 | - uses: actions/upload-artifact@v4 46 | if: ${{ !cancelled() }} 47 | with: 48 | name: playwright-report 49 | path: playwright-report/ 50 | retention-days: 1 51 | - name: Notify Discord on Failure 52 | if: failure() 53 | uses: appleboy/discord-action@v1.2.0 54 | with: 55 | webhook_url: ${{ secrets.DISCORD_WEBHOOK_URL }} 56 | color: "FF0000" # Red color for failure 57 | title: "GitHub Action Failed" 58 | message: | 59 | Workflow: ${{ github.workflow }} 60 | Job: ${{ github.job }} 61 | Run ID: ${{ github.run_id }} 62 | Repository: ${{ github.repository }} 63 | Branch: ${{ github.ref }} 64 | Commit: ${{ github.sha }} 65 | Error URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }} 66 | 67 | release_peer: 68 | if: ${{ github.event.inputs.tag != '' || startsWith(github.ref, 'refs/tags/v') }} 69 | runs-on: ubuntu-24.04 70 | needs: ['test'] 71 | permissions: 72 | contents: write 73 | id-token: write # The OIDC ID token is used for authentication with JSR. 74 | steps: 75 | - name: Checkout 76 | uses: actions/checkout@v4 77 | with: 78 | ref: ${{ github.event.inputs.tag || github.ref }} 79 | - uses: actions/setup-node@v4 80 | with: 81 | node-version: '20.x' 82 | registry-url: 'https://registry.npmjs.org' 83 | - name: Set version env 84 | run: echo "RELEASE_VERSION=$(git describe --tags --abbrev=0)" >> $GITHUB_ENV 85 | - uses: release-drafter/release-drafter@v5 86 | with: 87 | name: ${{ env.RELEASE_VERSION }} 88 | tag: ${{ env.RELEASE_VERSION }} 89 | version: ${{ env.RELEASE_VERSION }} 90 | publish: true 91 | template: | 92 | ## What’s Changed 93 | 94 | $CHANGES 95 | env: 96 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 97 | - run: npm ci 98 | - working-directory: ./peer 99 | run: | 100 | npx jsr publish --allow-slow-types 101 | npm run build 102 | npm publish --provenance --access public 103 | env: 104 | NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} 105 | 106 | publish_e2e_docker: 107 | runs-on: ubuntu-24.04 108 | if: false 109 | permissions: 110 | contents: read 111 | packages: write 112 | attestations: write 113 | id-token: write 114 | steps: 115 | - name: Checkout repository 116 | uses: actions/checkout@v4 117 | with: 118 | ref: ${{ github.event.inputs.tag || github.ref }} 119 | # Uses the `docker/login-action` action to log in to the Container registry registry using the account and password that will publish the packages. Once published, the packages are scoped to the account defined here. 120 | - name: Log in to the Container registry 121 | uses: docker/login-action@v3 122 | with: 123 | registry: ${{ env.REGISTRY }} 124 | username: ${{ github.actor }} 125 | password: ${{ secrets.GITHUB_TOKEN }} 126 | - 127 | name: Set up QEMU 128 | uses: docker/setup-qemu-action@v3 129 | - 130 | name: Set up Docker Buildx 131 | uses: docker/setup-buildx-action@v3 132 | # This step uses [docker/metadata-action](https://github.com/docker/metadata-action#about) to extract tags and labels that will be applied to the specified image. The `id` "meta" allows the output of this step to be referenced in a subsequent step. The `images` value provides the base name for the tags and labels. 133 | - name: Extract metadata (tags, labels) for Docker 134 | id: meta 135 | uses: docker/metadata-action@v5 136 | with: 137 | images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} 138 | # This step uses the `docker/build-push-action` action to build the image, based on your repository's `Dockerfile`. If the build succeeds, it pushes the image to GitHub Packages. 139 | # It uses the `context` parameter to define the build's context as the set of files located in the specified path. For more information, see "[Usage](https://github.com/docker/build-push-action#usage)" in the README of the `docker/build-push-action` repository. 140 | # It uses the `tags` and `labels` parameters to tag and label the image with the output from the "meta" step. 141 | - name: Build and push Docker image 142 | id: push 143 | uses: docker/build-push-action@v6 144 | with: 145 | context: . 146 | push: true 147 | tags: ${{ steps.meta.outputs.tags }} 148 | labels: ${{ steps.meta.outputs.labels }} 149 | # This step generates an artifact attestation for the image, which is an unforgeable statement about where and how it was built. It increases supply chain security for people who consume the image. For more information, see "[AUTOTITLE](/actions/security-guides/using-artifact-attestations-to-establish-provenance-for-builds)." 150 | - name: Generate artifact attestation 151 | uses: actions/attest-build-provenance@v2 152 | with: 153 | subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME}} 154 | subject-digest: ${{ steps.push.outputs.digest }} 155 | push-to-registry: true 156 | -------------------------------------------------------------------------------- /.github/workflows/release-please.yml: -------------------------------------------------------------------------------- 1 | on: 2 | push: 3 | branches: 4 | - main 5 | 6 | permissions: 7 | contents: write 8 | pull-requests: write 9 | 10 | name: release-please 11 | 12 | jobs: 13 | release-please: 14 | if: false 15 | runs-on: ubuntu-latest 16 | steps: 17 | - uses: googleapis/release-please-action@v4 18 | with: 19 | # this is a built-in strategy in release-please, see "Action Inputs" 20 | # for more options 21 | release-type: simple 22 | token: ${{ secrets.RELEASE_PLEASE_TOKEN }} 23 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | node_modules 2 | .parcel-cache 3 | /test-results/ 4 | /playwright-report/ 5 | /blob-report/ 6 | /playwright/.cache/ 7 | .DS_Store 8 | .vscode 9 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "peer/proto"] 2 | path = peer/proto 3 | url = git@github.com:PulseBeamDev/pulsebeam-proto.git 4 | -------------------------------------------------------------------------------- /.npmrc: -------------------------------------------------------------------------------- 1 | @jsr:registry=https://npm.jsr.io 2 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM mcr.microsoft.com/playwright:v1.49.1-noble 2 | 3 | WORKDIR /app 4 | RUN apt update && apt install -y make 5 | COPY . . 6 | RUN make install 7 | ENTRYPOINT ["make", "e2e"] 8 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Apache License 2 | Version 2.0, January 2004 3 | http://www.apache.org/licenses/ 4 | 5 | TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 6 | 7 | 1. Definitions. 8 | 9 | "License" shall mean the terms and conditions for use, reproduction, 10 | and distribution as defined by Sections 1 through 9 of this document. 11 | 12 | "Licensor" shall mean the copyright owner or entity authorized by 13 | the copyright owner that is granting the License. 14 | 15 | "Legal Entity" shall mean the union of the acting entity and all 16 | other entities that control, are controlled by, or are under common 17 | control with that entity. For the purposes of this definition, 18 | "control" means (i) the power, direct or indirect, to cause the 19 | direction or management of such entity, whether by contract or 20 | otherwise, or (ii) ownership of fifty percent (50%) or more of the 21 | outstanding shares, or (iii) beneficial ownership of such entity. 22 | 23 | "You" (or "Your") shall mean an individual or Legal Entity 24 | exercising permissions granted by this License. 25 | 26 | "Source" form shall mean the preferred form for making modifications, 27 | including but not limited to software source code, documentation 28 | source, and configuration files. 29 | 30 | "Object" form shall mean any form resulting from mechanical 31 | transformation or translation of a Source form, including but 32 | not limited to compiled object code, generated documentation, 33 | and conversions to other media types. 34 | 35 | "Work" shall mean the work of authorship, whether in Source or 36 | Object form, made available under the License, as indicated by a 37 | copyright notice that is included in or attached to the work 38 | (an example is provided in the Appendix below). 39 | 40 | "Derivative Works" shall mean any work, whether in Source or Object 41 | form, that is based on (or derived from) the Work and for which the 42 | editorial revisions, annotations, elaborations, or other modifications 43 | represent, as a whole, an original work of authorship. For the purposes 44 | of this License, Derivative Works shall not include works that remain 45 | separable from, or merely link (or bind by name) to the interfaces of, 46 | the Work and Derivative Works thereof. 47 | 48 | "Contribution" shall mean any work of authorship, including 49 | the original version of the Work and any modifications or additions 50 | to that Work or Derivative Works thereof, that is intentionally 51 | submitted to Licensor for inclusion in the Work by the copyright owner 52 | or by an individual or Legal Entity authorized to submit on behalf of 53 | the copyright owner. For the purposes of this definition, "submitted" 54 | means any form of electronic, verbal, or written communication sent 55 | to the Licensor or its representatives, including but not limited to 56 | communication on electronic mailing lists, source code control systems, 57 | and issue tracking systems that are managed by, or on behalf of, the 58 | Licensor for the purpose of discussing and improving the Work, but 59 | excluding communication that is conspicuously marked or otherwise 60 | designated in writing by the copyright owner as "Not a Contribution." 61 | 62 | "Contributor" shall mean Licensor and any individual or Legal Entity 63 | on behalf of whom a Contribution has been received by Licensor and 64 | subsequently incorporated within the Work. 65 | 66 | 2. Grant of Copyright License. Subject to the terms and conditions of 67 | this License, each Contributor hereby grants to You a perpetual, 68 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 69 | copyright license to reproduce, prepare Derivative Works of, 70 | publicly display, publicly perform, sublicense, and distribute the 71 | Work and such Derivative Works in Source or Object form. 72 | 73 | 3. Grant of Patent License. Subject to the terms and conditions of 74 | this License, each Contributor hereby grants to You a perpetual, 75 | worldwide, non-exclusive, no-charge, royalty-free, irrevocable 76 | (except as stated in this section) patent license to make, have made, 77 | use, offer to sell, sell, import, and otherwise transfer the Work, 78 | where such license applies only to those patent claims licensable 79 | by such Contributor that are necessarily infringed by their 80 | Contribution(s) alone or by combination of their Contribution(s) 81 | with the Work to which such Contribution(s) was submitted. If You 82 | institute patent litigation against any entity (including a 83 | cross-claim or counterclaim in a lawsuit) alleging that the Work 84 | or a Contribution incorporated within the Work constitutes direct 85 | or contributory patent infringement, then any patent licenses 86 | granted to You under this License for that Work shall terminate 87 | as of the date such litigation is filed. 88 | 89 | 4. Redistribution. You may reproduce and distribute copies of the 90 | Work or Derivative Works thereof in any medium, with or without 91 | modifications, and in Source or Object form, provided that You 92 | meet the following conditions: 93 | 94 | (a) You must give any other recipients of the Work or 95 | Derivative Works a copy of this License; and 96 | 97 | (b) You must cause any modified files to carry prominent notices 98 | stating that You changed the files; and 99 | 100 | (c) You must retain, in the Source form of any Derivative Works 101 | that You distribute, all copyright, patent, trademark, and 102 | attribution notices from the Source form of the Work, 103 | excluding those notices that do not pertain to any part of 104 | the Derivative Works; and 105 | 106 | (d) If the Work includes a "NOTICE" text file as part of its 107 | distribution, then any Derivative Works that You distribute must 108 | include a readable copy of the attribution notices contained 109 | within such NOTICE file, excluding those notices that do not 110 | pertain to any part of the Derivative Works, in at least one 111 | of the following places: within a NOTICE text file distributed 112 | as part of the Derivative Works; within the Source form or 113 | documentation, if provided along with the Derivative Works; or, 114 | within a display generated by the Derivative Works, if and 115 | wherever such third-party notices normally appear. The contents 116 | of the NOTICE file are for informational purposes only and 117 | do not modify the License. You may add Your own attribution 118 | notices within Derivative Works that You distribute, alongside 119 | or as an addendum to the NOTICE text from the Work, provided 120 | that such additional attribution notices cannot be construed 121 | as modifying the License. 122 | 123 | You may add Your own copyright statement to Your modifications and 124 | may provide additional or different license terms and conditions 125 | for use, reproduction, or distribution of Your modifications, or 126 | for any such Derivative Works as a whole, provided Your use, 127 | reproduction, and distribution of the Work otherwise complies with 128 | the conditions stated in this License. 129 | 130 | 5. Submission of Contributions. Unless You explicitly state otherwise, 131 | any Contribution intentionally submitted for inclusion in the Work 132 | by You to the Licensor shall be under the terms and conditions of 133 | this License, without any additional terms or conditions. 134 | Notwithstanding the above, nothing herein shall supersede or modify 135 | the terms of any separate license agreement you may have executed 136 | with Licensor regarding such Contributions. 137 | 138 | 6. Trademarks. This License does not grant permission to use the trade 139 | names, trademarks, service marks, or product names of the Licensor, 140 | except as required for reasonable and customary use in describing the 141 | origin of the Work and reproducing the content of the NOTICE file. 142 | 143 | 7. Disclaimer of Warranty. Unless required by applicable law or 144 | agreed to in writing, Licensor provides the Work (and each 145 | Contributor provides its Contributions) on an "AS IS" BASIS, 146 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 147 | implied, including, without limitation, any warranties or conditions 148 | of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A 149 | PARTICULAR PURPOSE. You are solely responsible for determining the 150 | appropriateness of using or redistributing the Work and assume any 151 | risks associated with Your exercise of permissions under this License. 152 | 153 | 8. Limitation of Liability. In no event and under no legal theory, 154 | whether in tort (including negligence), contract, or otherwise, 155 | unless required by applicable law (such as deliberate and grossly 156 | negligent acts) or agreed to in writing, shall any Contributor be 157 | liable to You for damages, including any direct, indirect, special, 158 | incidental, or consequential damages of any character arising as a 159 | result of this License or out of the use or inability to use the 160 | Work (including but not limited to damages for loss of goodwill, 161 | work stoppage, computer failure or malfunction, or any and all 162 | other commercial damages or losses), even if such Contributor 163 | has been advised of the possibility of such damages. 164 | 165 | 9. Accepting Warranty or Additional Liability. While redistributing 166 | the Work or Derivative Works thereof, You may choose to offer, 167 | and charge a fee for, acceptance of support, warranty, indemnity, 168 | or other liability obligations and/or rights consistent with this 169 | License. However, in accepting such obligations, You may act only 170 | on Your own behalf and on Your sole responsibility, not on behalf 171 | of any other Contributor, and only if You agree to indemnify, 172 | defend, and hold each Contributor harmless for any liability 173 | incurred by, or claims asserted against, such Contributor by reason 174 | of your accepting any such warranty or additional liability. 175 | 176 | END OF TERMS AND CONDITIONS 177 | 178 | APPENDIX: How to apply the Apache License to your work. 179 | 180 | To apply the Apache License to your work, attach the following 181 | boilerplate notice, with the fields enclosed by brackets "[]" 182 | replaced with your own identifying information. (Don't include 183 | the brackets!) The text should be enclosed in the appropriate 184 | comment syntax for the file format. We also recommend that a 185 | file or class name and description of purpose be included on the 186 | same "printed page" as the copyright notice for easier 187 | identification within third-party archives. 188 | 189 | Copyright [yyyy] [name of copyright owner] 190 | 191 | Licensed under the Apache License, Version 2.0 (the "License"); 192 | you may not use this file except in compliance with the License. 193 | You may obtain a copy of the License at 194 | 195 | http://www.apache.org/licenses/LICENSE-2.0 196 | 197 | Unless required by applicable law or agreed to in writing, software 198 | distributed under the License is distributed on an "AS IS" BASIS, 199 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 200 | See the License for the specific language governing permissions and 201 | limitations under the License. 202 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: e2e 2 | 3 | ci: 4 | npm ci 5 | 6 | bump: 7 | $(MAKE) -C peer bump VERSION=$(VERSION) 8 | 9 | publish: 10 | $(MAKE) -C peer publish 11 | 12 | install: 13 | npm install 14 | npx playwright install-deps 15 | npx playwright install 16 | 17 | test: 18 | $(MAKE) -C peer test 19 | npm run build -w peer 20 | npx playwright test --project=local -j 1 21 | 22 | test-local: 23 | PULSEBEAM_BASE_URL=http://localhost:3000 npx playwright test --project=local -j 2 24 | 25 | test-flaky: 26 | for i in `seq 100`; do echo $i; make test-local || break; done 27 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # @pulsebeam/client 2 | 3 | Simplifies real-time application development. Defines signaling protocol for connection establishment, handling media and data transmission, and provides infrastructure. 4 | 5 | ## Status 6 | 7 | > [!WARNING] 8 | > This SDK is currently in active development. We're currently brewing a homegrown WebRTC SFU implementation in Rust, https://github.com/pulseBeamDev/pulsebeam. 9 | > 10 | > • [Create GitHub Issues](https://github.com/PulseBeamDev/pulsebeam-js/issues) 11 | > • [Join PulseBeam Developer Discord](https://discord.gg/Bhd3t9afuB) 12 | 13 | ## Roadmap 14 | 15 | The project is in active development, please refer to the [roadmap](https://github.com/PulseBeamDev/pulsebeam-js/issues/6) to track our major milestones. 16 | 17 | ## Semantic Versioning 18 | 19 | This project adheres to [Semantic Versioning 2.0.0](https://semver.org/). 20 | 21 | * **MAJOR version (X.y.z):** Incompatible API changes. 22 | * **MINOR version (x.Y.z):** Functionality added in a backwards compatible manner. 23 | * **PATCH version (x.y.Z):** Backwards compatible bug fixes. 24 | 25 | ## WebRTC Resources 26 | 27 | For a deeper understanding of WebRTC concepts, consult the official WebRTC documentation: 28 | 29 | * https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API 30 | 31 | ## Related Links 32 | 33 | |Name|Link| 34 | |-|-| 35 | |PulseBeam Server|github.com/pulseBeamDev/pulsebeam| 36 | |Client SDK|https://github.com/PulseBeamDev/pulsebeam-js| 37 | |Server SDK|https://github.com/PulseBeamDev/pulsebeam-core| 38 | |FOSS Server|https://github.com/PulseBeamDev/pulsebeam-server-foss| 39 | |Signaling Protocol|https://github.com/PulseBeamDev/pulsebeam-proto| 40 | |Documentation|https://github.com/PulseBeamDev/docs| 41 | |PulseBeam Cloud|https://cloud.pulsebeam.dev| 42 | 43 | -------------------------------------------------------------------------------- /client-web/.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | pnpm-debug.log* 8 | lerna-debug.log* 9 | 10 | node_modules 11 | dist 12 | dist-ssr 13 | *.local 14 | 15 | # Editor directories and files 16 | .vscode/* 17 | !.vscode/extensions.json 18 | .idea 19 | .DS_Store 20 | *.suo 21 | *.ntvs* 22 | *.njsproj 23 | *.sln 24 | *.sw? 25 | -------------------------------------------------------------------------------- /client-web/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | Vite + Lit + TS 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | -------------------------------------------------------------------------------- /client-web/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "client-web", 3 | "private": true, 4 | "version": "0.0.0", 5 | "type": "module", 6 | "main": "./dist/pulsebeam.umd.cjs", 7 | "module": "./dist/pulsebeam.es.js", 8 | "types": "./dist/types/index.d.ts", 9 | "exports": { 10 | ".": { 11 | "require": { 12 | "types": "./dist/types/index.d.ts", 13 | "default": "./dist/pulsebeam.es.js" 14 | }, 15 | "default": { 16 | "types": "./dist/types/index.d.ts", 17 | "default": "./dist/pulsebeam.umd.js" 18 | } 19 | } 20 | }, 21 | "scripts": { 22 | "proto": "protoc --ts_out src/lib --proto_path proto proto/sfu.proto", 23 | "dev": "vite", 24 | "build": "tsc && vite build", 25 | "preview": "vite preview" 26 | }, 27 | "dependencies": { 28 | "@lit/context": "^1.1.5", 29 | "@protobuf-ts/runtime": "^2.10.0", 30 | "lit": "^3.3.0", 31 | "nanostores": "^1.0.1" 32 | }, 33 | "devDependencies": { 34 | "@protobuf-ts/plugin": "^2.10.0", 35 | "typescript": "~5.8.3", 36 | "vite": "^6.3.5", 37 | "vite-plugin-dts": "^4.5.4" 38 | } 39 | } 40 | -------------------------------------------------------------------------------- /client-web/proto/sfu.proto: -------------------------------------------------------------------------------- 1 | syntax = "proto3"; 2 | package sfu; 3 | 4 | // ------------------------------------- 5 | // Common Types 6 | // ------------------------------------- 7 | 8 | // Media configuration for a participant's stream 9 | message MediaConfig { 10 | bool audio = 1; // True if audio is active 11 | bool video = 2; // True if video is active 12 | } 13 | 14 | // Video quality preferences 15 | message VideoSettings { 16 | int32 max_height = 1; // Maximum height for the video stream 17 | } 18 | 19 | // State of a participant's stream 20 | message ParticipantStream { 21 | string participant_id = 1; // Unique SFU-internal ID 22 | string external_participant_id = 2; // Developer-provided user ID 23 | optional MediaConfig media = 3; // Media state (if unset, participant has left) 24 | } 25 | 26 | // ------------------------------------- 27 | // Client → Server 28 | // ------------------------------------- 29 | 30 | // Client message wrapper with sequence number for reliability 31 | message ClientMessage { 32 | uint32 sequence = 1; // Sequence number for message ordering/acknowledgment 33 | oneof msg { 34 | PublishIntent publish_intent = 2; 35 | VideoSubscription video_subscription = 3; 36 | } 37 | } 38 | 39 | // Intent to publish media 40 | message PublishIntent { 41 | MediaConfig media = 1; // Media to publish (audio/video) 42 | } 43 | 44 | // Subscriptions for receiving media from specific participants 45 | message VideoSubscription { 46 | repeated ParticipantSubscription subscriptions = 1; 47 | } 48 | 49 | // Subscription for a specific participant's video 50 | message ParticipantSubscription { 51 | string participant_id = 1; 52 | VideoSettings video_settings = 2; 53 | } 54 | 55 | // ------------------------------------- 56 | // Server → Client 57 | // ------------------------------------- 58 | 59 | // Server message wrapper 60 | message ServerMessage { 61 | oneof msg { 62 | RoomSnapshot room_snapshot = 1; 63 | StreamStateUpdate stream_update = 2; 64 | ActiveSpeakersUpdate active_speakers = 3; 65 | MessageAck message_ack = 4; 66 | ConnectionQuality connection_quality = 5; 67 | ErrorNotification error = 6; 68 | } 69 | } 70 | 71 | // Full snapshot of the room state 72 | message RoomSnapshot { 73 | repeated ParticipantStream participants = 1; 74 | string room_id = 2; // Room identifier for verification 75 | } 76 | 77 | // Incremental update of a participant's stream 78 | message StreamStateUpdate { 79 | ParticipantStream participant_stream = 1; 80 | } 81 | 82 | // Current active speakers in the room 83 | message ActiveSpeakersUpdate { 84 | repeated string participant_ids = 1; // Ordered by speaking activity (most active first) 85 | uint64 timestamp = 2; // Server timestamp for this update 86 | } 87 | 88 | // Connection quality metrics for adaptive streaming 89 | message ConnectionQuality { 90 | string participant_id = 1; // Which participant this applies to (empty = self) 91 | Quality quality = 2; // Connection quality level 92 | optional uint32 rtt_ms = 3; // Round-trip time in milliseconds 93 | } 94 | 95 | // Message acknowledgment (only for client message processing) 96 | message MessageAck { 97 | uint32 sequence = 1; // Sequence number being acknowledged 98 | bool success = 2; // Whether the message was processed successfully 99 | optional string message = 3; // Error details if success is false 100 | } 101 | 102 | // Server-initiated error notification 103 | message ErrorNotification { 104 | ErrorType type = 1; // Type of error 105 | string message = 2; // Human-readable error message 106 | bool fatal = 3; // Whether client should disconnect 107 | } 108 | 109 | // Connection quality levels 110 | enum Quality { 111 | EXCELLENT = 0; 112 | GOOD = 1; 113 | FAIR = 2; 114 | POOR = 3; 115 | DISCONNECTED = 4; 116 | } 117 | 118 | // Server-initiated error types 119 | enum ErrorType { 120 | ROOM_CLOSED = 0; // Room was closed by moderator/system 121 | PARTICIPANT_KICKED = 1; // Participant was removed from room 122 | SERVER_SHUTDOWN = 2; // Server is shutting down 123 | ROOM_CAPACITY_CHANGED = 3; // Room capacity reduced, participant removed 124 | AUTHENTICATION_EXPIRED = 4; // Auth token expired 125 | DUPLICATE_CONNECTION = 5; // Same participant connected elsewhere 126 | PROTOCOL_VIOLATION = 6; // Client sent malformed/invalid messages 127 | UNKNOWN_ERROR = 7; 128 | } 129 | 130 | -------------------------------------------------------------------------------- /client-web/public/vite.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /client-web/src/component.ts: -------------------------------------------------------------------------------- 1 | import { html, LitElement } from "lit"; 2 | import { customElement, property, query } from "lit/decorators.js"; 3 | import { consume, createContext, provide } from "@lit/context"; 4 | import { ClientCore } from "./lib"; 5 | import type { ParticipantMeta } from "./lib/core"; 6 | 7 | const clientContext = createContext(Symbol("client")); 8 | 9 | @customElement("pulsebeam-context") 10 | export class PulsebeamContext extends LitElement { 11 | @provide({ context: clientContext }) 12 | @property({ attribute: false }) 13 | value!: ClientCore; 14 | 15 | @query("slot") 16 | slotEl!: HTMLSlotElement; 17 | 18 | private audioElements: HTMLAudioElement[] = []; 19 | 20 | firstUpdated() { 21 | this.audioElements = Array.from(this.renderRoot.querySelectorAll("audio")); 22 | console.log("Audio elements:", this.audioElements); 23 | } 24 | 25 | render() { 26 | return html` 27 | 28 | 29 | 30 | 31 | 32 | `; 33 | } 34 | } 35 | 36 | @customElement("pulsebeam-video") 37 | export class PulsebeamVideo extends LitElement { 38 | @property({ attribute: false }) 39 | participantMeta?: ParticipantMeta; 40 | 41 | @consume({ context: clientContext, subscribe: true }) 42 | client?: ClientCore; 43 | 44 | @query("video") 45 | videoEl!: HTMLVideoElement; 46 | 47 | firstUpdated() { 48 | if (!this.client) { 49 | console.warn("No client context available"); 50 | return; 51 | } 52 | 53 | if (!this.participantMeta) { 54 | console.warn("No participant specified on "); 55 | return; 56 | } 57 | 58 | this.client.subscribeVideo(this.videoEl, this.participantMeta); 59 | } 60 | 61 | render() { 62 | return html``; 63 | } 64 | } 65 | 66 | declare global { 67 | interface HTMLElementTagNameMap { 68 | "pulsebeam-context": PulsebeamContext; 69 | "pulsebeam-video": PulsebeamVideo; 70 | } 71 | } 72 | -------------------------------------------------------------------------------- /client-web/src/index.ts: -------------------------------------------------------------------------------- 1 | import type { PulsebeamVideo } from "./component"; 2 | import { ClientCore } from "./lib"; 3 | export * from "./component"; 4 | 5 | const context = document.querySelector("pulsebeam-context"); 6 | 7 | (async () => { 8 | const client = new ClientCore({ 9 | sfuUrl: "http://localhost:3000/", 10 | maxDownstreams: 1, 11 | }); 12 | context!.value = client; 13 | 14 | const videos: Record = {}; 15 | client.$state.listen((v) => console.log(v)); 16 | client.$participants.listen(async (newValue, _, changed) => { 17 | // Create a new pulsebeam-video element if not already present 18 | let video = videos[changed]; 19 | if (video) { 20 | return; 21 | } 22 | 23 | video = document.createElement("pulsebeam-video") as PulsebeamVideo; 24 | videos[changed] = video; 25 | await video.updateComplete; 26 | 27 | // Set participantMeta on the pulsebeam-video element 28 | const participantMeta = newValue[changed].get(); // Get the metadata for the participant 29 | video.participantMeta = participantMeta; 30 | console.log(participantMeta); 31 | 32 | // Append the video to the DOM 33 | context!.appendChild(video); 34 | }); 35 | await client.connect("default", `alice-${Math.round(Math.random() * 100)}`); 36 | 37 | const stream = await navigator.mediaDevices.getUserMedia({ 38 | video: true, 39 | }); 40 | 41 | client.publish(stream); 42 | })(); 43 | -------------------------------------------------------------------------------- /client-web/src/lib/core.ts: -------------------------------------------------------------------------------- 1 | import { 2 | ClientMessage, 3 | MediaConfig, 4 | ParticipantStream, 5 | ParticipantSubscription, 6 | ServerMessage, 7 | } from "./sfu.ts"; 8 | import { 9 | atom, 10 | map, 11 | type PreinitializedMapStore, 12 | type PreinitializedWritableAtom, 13 | } from "nanostores"; 14 | 15 | const MAX_DOWNSTREAMS = 16; 16 | const LAST_N_AUDIO = 3; 17 | const DEBOUNCE_DELAY_MS = 500; 18 | 19 | // Internal Ids 20 | type ParticipantId = string; 21 | 22 | interface VideoSlot { 23 | trans: RTCRtpTransceiver; 24 | participantId?: ParticipantId; 25 | } 26 | 27 | export interface ParticipantMeta { 28 | externalParticipantId: string; 29 | participantId: string; 30 | media: MediaConfig; 31 | stream: MediaStream; 32 | maxHeight: number; 33 | } 34 | 35 | export interface ClientCoreConfig { 36 | sfuUrl: string; 37 | maxDownstreams: number; 38 | } 39 | 40 | export class ClientCore { 41 | #sfuUrl: string; 42 | #pc: RTCPeerConnection; 43 | #rpc: RTCDataChannel; 44 | #videoSender: RTCRtpTransceiver; 45 | #audioSender: RTCRtpTransceiver; 46 | #closed: boolean; 47 | #sequence: number; 48 | 49 | #videoSlots: VideoSlot[]; 50 | #audioSlots: RTCRtpTransceiver[]; 51 | #timeoutId: ReturnType | null; 52 | 53 | $participants: PreinitializedMapStore< 54 | Record> 55 | >; 56 | $state: PreinitializedWritableAtom; 57 | 58 | constructor(cfg: ClientCoreConfig) { 59 | this.#sfuUrl = cfg.sfuUrl; 60 | const maxDownstreams = Math.max( 61 | Math.min(cfg.maxDownstreams, MAX_DOWNSTREAMS), 62 | 0, 63 | ); 64 | this.#closed = false; 65 | this.#videoSlots = []; 66 | this.#audioSlots = []; 67 | this.#sequence = 0; 68 | this.#timeoutId = null; 69 | this.$participants = map({}); 70 | this.$state = atom("new"); 71 | 72 | this.#pc = new RTCPeerConnection(); 73 | this.#pc.onconnectionstatechange = () => { 74 | const connectionState = this.#pc.connectionState; 75 | console.debug(`PeerConnection state changed: ${connectionState}`); 76 | this.$state.set(connectionState); 77 | if ( 78 | connectionState === "failed" || connectionState === "closed" || 79 | connectionState === "disconnected" 80 | ) { 81 | this.#close( 82 | `PeerConnection state became: ${connectionState}`, 83 | ); 84 | } 85 | }; 86 | 87 | // SFU RPC DataChannel 88 | this.#rpc = this.#pc.createDataChannel("pulsebeam::rpc"); 89 | this.#rpc.binaryType = "arraybuffer"; 90 | this.#rpc.onmessage = (event: MessageEvent) => { 91 | try { 92 | const serverMessage = ServerMessage.fromBinary( 93 | new Uint8Array(event.data as ArrayBuffer), 94 | ); 95 | const msg = serverMessage.msg; 96 | const msgKind = msg.oneofKind; 97 | if (!msgKind) { 98 | console.warn("Received SFU message with undefined payload kind."); 99 | return; 100 | } 101 | 102 | switch (msgKind) { 103 | case "roomSnapshot": 104 | this.#handleParticipantUpdates(msg.roomSnapshot.participants); 105 | break; 106 | case "streamUpdate": 107 | if (msg.streamUpdate.participantStream) { 108 | this.#handleParticipantUpdates([ 109 | msg.streamUpdate.participantStream, 110 | ]); 111 | } 112 | break; 113 | } 114 | // TODO: implement this 115 | } catch (e: any) { 116 | this.#close(`Error processing SFU RPC message: ${e}`); 117 | } 118 | }; 119 | this.#rpc.onclose = () => { 120 | this.#close("Internal RPC closed prematurely"); 121 | }; 122 | this.#rpc.onerror = (e) => { 123 | this.#close(`Internal RPC closed prematurely with an error: ${e}`); 124 | }; 125 | 126 | // Transceivers 127 | this.#videoSender = this.#pc.addTransceiver("video", { 128 | direction: "sendonly", 129 | }); 130 | this.#audioSender = this.#pc.addTransceiver("audio", { 131 | direction: "sendonly", 132 | }); 133 | 134 | for (let i = 0; i < LAST_N_AUDIO; i++) { 135 | this.#pc.addTransceiver("audio", { 136 | direction: "recvonly", 137 | }); 138 | } 139 | 140 | for (let i = 0; i < maxDownstreams; i++) { 141 | this.#pc.addTransceiver("video", { 142 | direction: "recvonly", 143 | }); 144 | } 145 | } 146 | 147 | #sendRpc(msg: ClientMessage["msg"]) { 148 | this.#rpc.send(ClientMessage.toBinary({ 149 | sequence: this.#sequence, 150 | msg, 151 | })); 152 | this.#sequence += 1; 153 | } 154 | 155 | #handleParticipantUpdates(streams: ParticipantStream[]) { 156 | const newParticipants: ParticipantMeta[] = []; 157 | 158 | for (const stream of streams) { 159 | if (!stream.media) { 160 | // participant has left 161 | this.$participants.setKey(stream.participantId, undefined); 162 | continue; 163 | } 164 | 165 | if (stream.participantId in this.$participants.get()) { 166 | const participant = this.$participants.get()[stream.participantId]; 167 | participant.setKey("media", stream.media); 168 | participant.setKey( 169 | "externalParticipantId", 170 | stream.externalParticipantId, 171 | ); 172 | participant.setKey("participantId", stream.participantId); 173 | } else { 174 | const meta: ParticipantMeta = { 175 | externalParticipantId: stream.externalParticipantId, 176 | participantId: stream.participantId, 177 | media: stream.media, 178 | stream: new MediaStream(), 179 | maxHeight: 0, // default invisible until the UI tells us to render 180 | }; 181 | 182 | const reactiveMeta = atom(meta); 183 | reactiveMeta.listen((_) => { 184 | this.#triggerSubscriptionFeedback(); 185 | }); 186 | this.$participants.setKey(stream.participantId, atom(meta)); 187 | newParticipants.push(meta); 188 | } 189 | } 190 | 191 | // TODO: should we bin pack the old participants first? 192 | for (const slot of this.#videoSlots) { 193 | if (slot.participantId) { 194 | if (slot.participantId in this.$participants) { 195 | continue; 196 | } 197 | 198 | slot.participantId = undefined; 199 | } 200 | 201 | const participant = newParticipants.pop(); 202 | if (!participant) { 203 | continue; 204 | } 205 | 206 | slot.participantId = participant.participantId; 207 | } 208 | 209 | this.#triggerSubscriptionFeedback(); 210 | } 211 | 212 | #close(error?: string) { 213 | if (this.#closed) return; 214 | 215 | if (error) { 216 | console.error("exited with an error:", error); 217 | } 218 | 219 | this.#closed = true; 220 | } 221 | 222 | #triggerSubscriptionFeedback() { 223 | if (this.#timeoutId) { 224 | return; 225 | } 226 | 227 | this.#timeoutId = setTimeout(() => { 228 | const subscriptions: ParticipantSubscription[] = Object.values( 229 | this.$participants, 230 | ).map((p) => ({ 231 | participantId: p.participantId, 232 | videoSettings: { 233 | maxHeight: p.maxHeight, 234 | }, 235 | })); 236 | this.#sendRpc({ 237 | oneofKind: "videoSubscription", 238 | videoSubscription: { 239 | subscriptions, 240 | }, 241 | }); 242 | }, DEBOUNCE_DELAY_MS); 243 | } 244 | 245 | async connect(room: string, participant: string) { 246 | if (this.#closed) { 247 | const errorMessage = 248 | "This client instance has been terminated and cannot be reused."; 249 | console.error(errorMessage); 250 | throw new Error(errorMessage); // More direct feedback to developer 251 | } 252 | 253 | if (this.#pc.connectionState != "new") { 254 | const errorMessage = 255 | "This client instance has been initiated and cannot be reused."; 256 | console.error(errorMessage); 257 | throw new Error(errorMessage); // More direct feedback to developer 258 | } 259 | 260 | try { 261 | const offer = await this.#pc.createOffer(); 262 | await this.#pc.setLocalDescription(offer); 263 | const response = await fetch( 264 | `${this.#sfuUrl}?room=${room}&participant=${participant}`, 265 | { 266 | method: "POST", 267 | body: offer.sdp!, 268 | headers: { "Content-Type": "application/sdp" }, 269 | }, 270 | ); 271 | if (!response.ok) { 272 | throw new Error( 273 | `Signaling request failed: ${response.status} ${await response 274 | .text()}`, 275 | ); 276 | } 277 | await this.#pc.setRemoteDescription({ 278 | type: "answer", 279 | sdp: await response.text(), 280 | }); 281 | 282 | // https://blog.mozilla.org/webrtc/rtcrtptransceiver-explored/ 283 | // transceivers order is stable, and mid is only defined after setLocalDescription 284 | const transceivers = this.#pc.getTransceivers(); 285 | for (const trans of transceivers) { 286 | if (trans.direction === "sendonly") { 287 | continue; 288 | } 289 | 290 | if (trans.receiver.track.kind === "audio") { 291 | this.#audioSlots.push(trans); 292 | } else if (trans.receiver.track.kind === "video") { 293 | this.#videoSlots.push({ 294 | trans, 295 | }); 296 | } 297 | } 298 | 299 | // Status transitions to "connected" will be handled by onconnectionstatechange 300 | } catch (error: any) { 301 | this.#close( 302 | error.message || "Signaling process failed unexpectedly.", 303 | ); 304 | } 305 | } 306 | 307 | disconnect() { 308 | if (this.#timeoutId) { 309 | clearTimeout(this.#timeoutId); 310 | } 311 | this.#pc.close(); 312 | } 313 | 314 | publish(stream: MediaStream) { 315 | const videoTracks = stream.getVideoTracks(); 316 | if (videoTracks.length > 1) { 317 | throw new Error( 318 | `Unexpected MediaStream composition: Expected at most one video track, but found ${videoTracks.length}. This component or function is designed to handle a single video source and/or a single audio source.`, 319 | ); 320 | } 321 | 322 | const audioTracks = stream.getAudioTracks(); 323 | if (audioTracks.length > 1) { 324 | throw new Error( 325 | `Unexpected MediaStream composition: Expected at most one audio track, but found ${audioTracks.length}. This component or function is designed to handle a single audio source and/or a single audio source.`, 326 | ); 327 | } 328 | 329 | const newVideoTrack = videoTracks.at(0) || null; 330 | this.#videoSender.sender.replaceTrack(newVideoTrack); 331 | 332 | const newAudioTrack = audioTracks.at(0) || null; 333 | this.#audioSender.sender.replaceTrack(newAudioTrack); 334 | } 335 | 336 | unpublish() { 337 | this.#videoSender.sender.replaceTrack(null); 338 | this.#audioSender.sender.replaceTrack(null); 339 | } 340 | 341 | // TODO: remove browser specific 342 | subscribeVideo(video: HTMLVideoElement, participant: ParticipantMeta) { 343 | video.srcObject = participant.stream; 344 | video.autoplay = true; 345 | } 346 | 347 | subscribeAudio(audio: HTMLAudioElement) { 348 | } 349 | } 350 | -------------------------------------------------------------------------------- /client-web/src/lib/index.ts: -------------------------------------------------------------------------------- 1 | export { ClientCore, type ClientCoreConfig } from "./core.ts"; 2 | -------------------------------------------------------------------------------- /client-web/src/vite-env.d.ts: -------------------------------------------------------------------------------- 1 | /// 2 | -------------------------------------------------------------------------------- /client-web/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2020", 4 | "experimentalDecorators": true, 5 | "useDefineForClassFields": false, 6 | "module": "ESNext", 7 | "lib": [ 8 | "ES2020", 9 | "DOM", 10 | "DOM.Iterable" 11 | ], 12 | "skipLibCheck": true, 13 | /* Bundler mode */ 14 | "moduleResolution": "bundler", 15 | "allowImportingTsExtensions": true, 16 | "verbatimModuleSyntax": true, 17 | "moduleDetection": "force", 18 | "noEmit": true, 19 | /* Linting */ 20 | "strict": true, 21 | "noUnusedLocals": true, 22 | "noUnusedParameters": true, 23 | "erasableSyntaxOnly": true, 24 | "noFallthroughCasesInSwitch": true, 25 | "noUncheckedSideEffectImports": true 26 | }, 27 | "include": [ 28 | "src" 29 | ] 30 | } 31 | -------------------------------------------------------------------------------- /client-web/vite.config.ts: -------------------------------------------------------------------------------- 1 | import { defineConfig } from "vite"; 2 | import path from "path"; 3 | import dts from "vite-plugin-dts"; 4 | 5 | export default defineConfig({ 6 | plugins: [ 7 | dts({ 8 | insertTypesEntry: true, 9 | outDir: "dist/types", 10 | tsconfigPath: "./tsconfig.json", 11 | }), 12 | ], 13 | build: { 14 | // Output directory for the built library 15 | outDir: "dist", 16 | // Minify the output 17 | minify: true, // 'esbuild' or true for terser, false to disable 18 | // Generate source maps 19 | sourcemap: true, 20 | lib: { 21 | // The entry point for your library (exports all components) 22 | entry: path.resolve(__dirname, "src/index.ts"), 23 | // The name for the UMD build (if you're creating one) 24 | name: "Pulsebeam", 25 | // Output formats 26 | formats: ["es", "umd"], 27 | // Filename for the generated bundle (without extension) 28 | // The [format] placeholder will be replaced by 'es', 'cjs', or 'umd' 29 | fileName: (format) => `pulsebeam.${format}.js`, 30 | }, 31 | // rollupOptions: { 32 | // // Make sure to externalize dependencies that shouldn't be bundled 33 | // // into your library (Lit itself should be a peer dependency) 34 | // external: ["lit", /^lit\/.*/], 35 | // output: { 36 | // // Provide global variables to use in the UMD build 37 | // // for externalized deps 38 | // globals: { 39 | // "lit": "Lit", 40 | // "lit/decorators.js": "LitDecorators", // Adjust if you import directly 41 | // "lit/html.js": "LitHtml", // Adjust 42 | // // Add other lit direct imports if you use them, e.g. 'lit/directives/class-map.js' 43 | // }, 44 | // // If you want to export CSS separately (Less common for Lit components with Shadow DOM) 45 | // // assetFileNames: (assetInfo) => { 46 | // // if (assetInfo.name === 'style.css') return 'my-lit-library.css'; 47 | // // return assetInfo.name; 48 | // // }, 49 | // }, 50 | // }, 51 | }, 52 | }); 53 | -------------------------------------------------------------------------------- /demo-cdn/README.md: -------------------------------------------------------------------------------- 1 | # PulseBeam WebRTC DataChannel Example 2 | 3 | ### Run Demo 4 | 1. Install dependencies with `npm i` 5 | 1. Run with `npm start` 6 | 1. Go to your browser open two tabs: 7 | - URL for first tab: `http://localhost:3000/?development=true&peerId=peer-29` 8 | - URL for second tab: `http://localhost:3000/?development=true` 9 | 1. On the second tab say `peer-29` in the first text box. Then click connect. 10 | 1. You can edit the text in the bottom text box. And see it synchronizing between the peers. 11 | 1. Note: This demo will work globally within the scope of your project-id (not just two tabs within the same browser!). So feel free to have the one peer on a different network or machine. 12 | 1. If desired, go to inspector, console to see logs on either tab 13 | 14 | ### So [what happened?](https://pulsebeam.dev/docs/getting-started/what-happened/) 15 | 16 | ### For more information, see [related docs](https://pulsebeam.dev/docs/getting-started/quick-start/) 17 | 18 | ### Unfamiliar terms? See [glossary](https://pulsebeam.dev/docs/concepts/terms/) 19 | 20 | ### When running our demos locally, PulseBeam convention states: 21 | * Demo will use the local `/auth` server defined here (in `../demo-server`) 22 | * Adding `development=true` as a URL parameter will use insecure [development auth](https://pulsebeam.dev/docs/getting-started/quick-start/) 23 | 24 | ### Our demos: 25 | * Data channel `demo-cdn`, our [quickstart demo](https://pulsebeam.dev/docs/getting-started/quick-start/) 26 | * Video `../demo-react`, our [video chat demo](https://meet.pulsebeam.dev/) 27 | 28 | ### For questions, [contact us](https://pulsebeam.dev/docs/community-and-support/support/) -------------------------------------------------------------------------------- /demo-cdn/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | PulseBeam Demo - CDN 8 | 9 | 10 | 11 | 12 | 13 |
14 |
15 | person 16 |
17 |

Start chatting with another peer

18 |
19 | 25 |
26 |
27 | 28 |
29 |
30 |
31 |
32 | 33 |
34 |
35 |
36 | 37 | 175 | 176 | 177 | 178 | -------------------------------------------------------------------------------- /demo-cdn/main.js: -------------------------------------------------------------------------------- 1 | import handler from "serve-handler"; 2 | import http from "http"; 3 | import { auth } from "@pulsebeam/demo-server"; 4 | 5 | const server = http.createServer((req, res) => { 6 | // URL requires a base url... 7 | const url = new URL(req.url, `http://${req.headers.host}`); 8 | if (url.pathname === "/auth") { 9 | try { 10 | const token = auth(url); 11 | res.writeHead(200, { 12 | "Content-Type": "text/plain; charset=utf-8", 13 | }); 14 | res.end(token); 15 | } catch (e) { 16 | console.log(e) 17 | if (e.message.includes("Key")){ 18 | res.writeHead(500, { "Content-Type": "text/plain" }); 19 | res.end("Server Error - keys are required"); 20 | } else { 21 | res.writeHead(400, { "Content-Type": "text/plain" }); 22 | res.end("Bad Request - groupId and peerId are required"); 23 | } 24 | } 25 | return; 26 | } 27 | 28 | // You pass two more arguments for config and middleware 29 | // More details here: https://github.com/vercel/serve-handler#options 30 | return handler(req, res); 31 | }); 32 | 33 | server.listen(3000, () => { 34 | console.log("Running at http://localhost:3000"); 35 | }); 36 | -------------------------------------------------------------------------------- /demo-cdn/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@pulsebeam/demo-cdn", 3 | "version": "1.0.0", 4 | "main": "main.js", 5 | "type": "module", 6 | "license": "Apache-2.0", 7 | "author": "Lukas Herman support@pulsebeam.dev", 8 | "repository": { 9 | "type": "git", 10 | "url": "https://github.com/PulseBeamDev/pulsebeam-js.git" 11 | }, 12 | "homepage": "https://pulsebeam.dev", 13 | "scripts": { 14 | "start": "node --experimental-wasm-modules main.js" 15 | }, 16 | "keywords": [], 17 | "description": "", 18 | "dependencies": { 19 | "@pulsebeam/demo-server": "^1.0.0", 20 | "serve-handler": "^6.1.6" 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /demo-react/.gitignore: -------------------------------------------------------------------------------- 1 | # Logs 2 | logs 3 | *.log 4 | npm-debug.log* 5 | yarn-debug.log* 6 | yarn-error.log* 7 | pnpm-debug.log* 8 | lerna-debug.log* 9 | 10 | node_modules 11 | dist 12 | dist-ssr 13 | *.local 14 | 15 | # Editor directories and files 16 | .vscode/* 17 | !.vscode/extensions.json 18 | .idea 19 | .DS_Store 20 | *.suo 21 | *.ntvs* 22 | *.njsproj 23 | *.sln 24 | *.sw? 25 | .vite 26 | .wrangler 27 | -------------------------------------------------------------------------------- /demo-react/README.md: -------------------------------------------------------------------------------- 1 | # PulseBeam WebRTC Video Call Example 2 | 3 | ### Run Demo 4 | 1. `npm i` 5 | 1. Set key (get key [here](https://cloud.pulsebeam.dev/)) 6 | ``` 7 | export PULSEBEAM_API_KEY=kid_<...> 8 | export PULSEBEAM_API_SECRET=sk_<...> 9 | ``` 10 | 1. `npm run dev` 11 | 12 | ### Use Demo 13 | 1. Go to your browser open two tabs: 14 | - URL for first tab: `http://localhost:5174/` 15 | - URL for second tab: `http://localhost:5174/` 16 | 1. In each tab enter a name (e.g. alice, bob) 17 | 1. In one tab, enter the other's name into one tab (e.g. alice call bob) 18 | 1. Click connect, and the peers will connect to each other in a video call 19 | 1. Note: This demo will work globally within the scope of your project-id (not just two tabs within the same browser!). So feel free to have the one peer on a different network or machine. 20 | 1. If desired, go to inspector, console to see logs on either tab 21 | 22 | ### Unfamiliar terms? See [glossary](https://pulsebeam.dev/docs/concepts/terms/) 23 | 24 | ### So what happened? See [concepts](https://pulsebeam.dev/docs/concepts/terms/) 25 | 26 | ### When running our demos locally, PulseBeam convention states: 27 | * Demo will use the local `/auth` server defined here (in `../demo-server`) 28 | * Adding `development=true` as a URL parameter will use insecure [development auth](https://pulsebeam.dev/docs/getting-started/quick-start/) 29 | 30 | ### Our demos: 31 | * Data channel `../demo-cdn`, our [quickstart demo](https://pulsebeam.dev/docs/getting-started/quick-start/) 32 | * Video `demo-react`, our [video chat demo](https://meet.pulsebeam.dev/) 33 | 34 | ### For questions, [contact us](https://pulsebeam.dev/docs/community-and-support/support/) -------------------------------------------------------------------------------- /demo-react/eslint.config.js: -------------------------------------------------------------------------------- 1 | import js from '@eslint/js' 2 | import globals from 'globals' 3 | import reactHooks from 'eslint-plugin-react-hooks' 4 | import reactRefresh from 'eslint-plugin-react-refresh' 5 | import tseslint from 'typescript-eslint' 6 | 7 | export default tseslint.config( 8 | { ignores: ['dist'] }, 9 | { 10 | extends: [js.configs.recommended, ...tseslint.configs.recommended], 11 | files: ['**/*.{ts,tsx}'], 12 | languageOptions: { 13 | ecmaVersion: 2020, 14 | globals: globals.browser, 15 | }, 16 | plugins: { 17 | 'react-hooks': reactHooks, 18 | 'react-refresh': reactRefresh, 19 | }, 20 | rules: { 21 | ...reactHooks.configs.recommended.rules, 22 | 'react-refresh/only-export-components': [ 23 | 'warn', 24 | { allowConstantExport: true }, 25 | ], 26 | }, 27 | }, 28 | ) 29 | -------------------------------------------------------------------------------- /demo-react/functions/auth.ts: -------------------------------------------------------------------------------- 1 | import { AccessToken, PeerClaims, PeerPolicy } from "@pulsebeam/server/workerd"; 2 | 3 | interface Env { 4 | PULSEBEAM_API_KEY: string; 5 | PULSEBEAM_API_SECRET: string; 6 | } 7 | 8 | export const onRequest: PagesFunction = async (context) => { 9 | const url = new URL(context.request.url); 10 | const groupId = url.searchParams.get("groupId"); 11 | const peerId = url.searchParams.get("peerId"); 12 | 13 | if (!groupId || !peerId) { 14 | throw new Error("groupId and peerId are required"); 15 | } 16 | 17 | const claims = new PeerClaims(groupId, peerId); 18 | const rule = new PeerPolicy("*", "*"); 19 | claims.setAllowPolicy(rule); 20 | claims.setAllowPolicy(rule); 21 | 22 | const app = new AccessToken( 23 | context.env.PULSEBEAM_API_KEY, 24 | context.env.PULSEBEAM_API_SECRET, 25 | ); 26 | const token = app.createToken(claims, 3600); 27 | return new Response(token); 28 | }; 29 | -------------------------------------------------------------------------------- /demo-react/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | Meet 11 | 12 | 13 | 14 |
15 | 16 | 17 | 18 | 19 | -------------------------------------------------------------------------------- /demo-react/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@pulsebeam/demo-react", 3 | "private": true, 4 | "version": "0.0.0", 5 | "type": "module", 6 | "license": "Apache-2.0", 7 | "author": "Lukas Herman support@pulsebeam.dev", 8 | "repository": { 9 | "type": "git", 10 | "url": "https://github.com/PulseBeamDev/pulsebeam-js.git" 11 | }, 12 | "homepage": "https://pulsebeam.dev", 13 | "scripts": { 14 | "dev": "NODE_OPTIONS='--experimental-wasm-modules' vite --host", 15 | "build": "NODE_OPTIONS='--experimental-wasm-modules' vite build", 16 | "lint": "eslint .", 17 | "preview": "NODE_OPTIONS='--experimental-wasm-modules' vite preview" 18 | }, 19 | "dependencies": { 20 | "@nanostores/react": "^0.8.4", 21 | "@pulsebeam/demo-server": "^1.0.0", 22 | "@pulsebeam/peer": "*", 23 | "@pulsebeam/server": "^0.0.29", 24 | "@theopenweb/get-user-media-mock": "^1.0.0", 25 | "immer": "^10.1.1", 26 | "react": "^19.0.0", 27 | "react-dom": "^19.0.0", 28 | "zustand": "^5.0.1" 29 | }, 30 | "devDependencies": { 31 | "@cloudflare/workers-types": "^4.20250121.0", 32 | "@eslint/js": "^9.13.0", 33 | "@types/node": "^22.10.7", 34 | "@types/react": "^19.0.3", 35 | "@types/react-dom": "^19.0.3", 36 | "@vitejs/plugin-react-swc": "^3.5.0", 37 | "eslint": "^9.13.0", 38 | "eslint-plugin-react-hooks": "^5.0.0", 39 | "eslint-plugin-react-refresh": "^0.4.14", 40 | "globals": "^15.11.0", 41 | "typescript": "~5.7.3", 42 | "typescript-eslint": "^8.11.0", 43 | "vite": "^6.1.0", 44 | "wrangler": "^3.108.1" 45 | }, 46 | "optionalDependencies": { 47 | "@rollup/rollup-linux-x64-gnu": "4.34.6" 48 | } 49 | } 50 | -------------------------------------------------------------------------------- /demo-react/public/vite.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /demo-react/src/App.tsx: -------------------------------------------------------------------------------- 1 | import { 2 | createContext, 3 | FormEvent, 4 | useContext, 5 | useEffect, 6 | useRef, 7 | useState, 8 | } from "react"; 9 | import { useSyncURLWithState } from "./util.ts"; 10 | import { createPeer, PeerStore } from "@pulsebeam/peer"; 11 | import { useStore } from "@nanostores/react"; 12 | // @ts-ignore: no type 13 | import GetUserMediaMock from "@theopenweb/get-user-media-mock"; 14 | 15 | const PeerContext = createContext(null); 16 | 17 | export default function App() { 18 | const [peer, setPeer] = useState(null); 19 | 20 | return ( 21 | 22 | {peer === null 23 | ? 24 | : setPeer(null)} />} 25 | 26 | ); 27 | } 28 | 29 | interface JoinPageProps { 30 | onJoined: (peer: PeerStore) => void; 31 | } 32 | 33 | function JoinPage(props: JoinPageProps) { 34 | const [loading, setLoading] = useState(false); 35 | const [streamLoading, setStreamLoading] = useState(false); 36 | const [baseUrl, setBaseUrl] = useSyncURLWithState( 37 | "baseUrl", 38 | "https://cloud.pulsebeam.dev/grpc", 39 | ); 40 | const [roomId, setRoomId] = useSyncURLWithState("roomId", ""); 41 | const [peerId, setPeerId] = useSyncURLWithState("peerId", ""); 42 | const [forceRelay, setForceRelay] = useSyncURLWithState( 43 | "forceRelay", 44 | "off", 45 | ); 46 | const [mock, setMock] = useSyncURLWithState("mock", "off"); 47 | const [stream, setStream] = useState(null); 48 | 49 | useEffect(() => { 50 | (async () => { 51 | setStreamLoading(true); 52 | let localStream; 53 | if (mock === "on") { 54 | const mediaMock = new GetUserMediaMock(); 55 | localStream = await mediaMock.getMockCanvasStream({ video: true }); 56 | } else { 57 | localStream = await navigator.mediaDevices.getUserMedia({ 58 | video: true, 59 | audio: true, 60 | }); 61 | localStream.getAudioTracks().forEach((t) => t.enabled = false); 62 | } 63 | 64 | setStream(localStream); 65 | setStreamLoading(false); 66 | })(); 67 | }, [mock]); 68 | 69 | const onJoin = async () => { 70 | if (!stream) return; 71 | 72 | setLoading(true); 73 | try { 74 | // See https://pulsebeam.dev/docs/guides/token/#example-nodejs-http-server 75 | // For explanation of this token-serving method 76 | const resp = await fetch( 77 | `/auth?groupId=${roomId}&peerId=${peerId}`, 78 | ); 79 | 80 | const token = await resp.text(); 81 | const peer = await createPeer({ 82 | token, 83 | forceRelay: forceRelay === "on", 84 | baseUrl: baseUrl, 85 | }); 86 | const peerStore = new PeerStore(peer); 87 | peerStore.$streams.setKey("camera", stream); 88 | props.onJoined(peerStore); 89 | } finally { 90 | setLoading(false); 91 | } 92 | }; 93 | 94 | return ( 95 |
96 |
100 | 106 |
{ 108 | e.preventDefault(); 109 | onJoin(); 110 | }} 111 | > 112 | 174 |
175 |
176 |
177 | ); 178 | } 179 | 180 | interface SessionPageProps { 181 | onClosed: () => void; 182 | } 183 | 184 | function SessionPage(props: SessionPageProps) { 185 | const peerStore = useContext(PeerContext)!; 186 | const localStreams = useStore(peerStore.$streams); 187 | const remotePeersMap = useStore(peerStore.$remotePeers); 188 | const [muted, setMuted] = useState(true); 189 | const [hideChat, setHideChat] = useState(true); 190 | const [screenShare, setScreenShare] = useState(false); 191 | const state = useStore(peerStore.$state); 192 | 193 | useEffect(() => { 194 | if (state === "closed") { 195 | props.onClosed(); 196 | } 197 | }, [state]); 198 | 199 | useEffect(() => { 200 | (async () => { 201 | if (screenShare) { 202 | const stream = await navigator.mediaDevices.getDisplayMedia(); 203 | peerStore.$streams.setKey("screen", stream); 204 | } else { 205 | peerStore.$streams.setKey("screen", undefined); 206 | } 207 | })(); 208 | }, [screenShare]); 209 | 210 | const remotePeers = Object.values(remotePeersMap); 211 | 212 | return ( 213 |
214 | 256 | 257 |
292 | ); 293 | } 294 | 295 | interface ChatDialogProps { 296 | hidden: boolean; 297 | onClose: () => void; 298 | } 299 | 300 | function ChatDialog(props: ChatDialogProps) { 301 | const peerStore = useContext(PeerContext)!; 302 | const [text, setText] = useState(""); 303 | const history = useStore(peerStore.$kv); 304 | const sortedHistory = Object.entries(history).sort((a, b) => 305 | a[0].localeCompare(b[0]) 306 | ); 307 | 308 | const onSubmit = (e: FormEvent) => { 309 | e.preventDefault(); 310 | 311 | const key = `${Date.now()}:${peerStore.peer.peerId}`; 312 | peerStore.$kv.setKey(key, text); 313 | setText(""); 314 | }; 315 | 316 | return ( 317 | 318 | 324 | 325 | 345 | 346 | 362 | 363 | ); 364 | } 365 | 366 | interface VideoContainerProps { 367 | title: string; 368 | stream: MediaStream | null; 369 | loading: boolean; 370 | className: string; 371 | } 372 | 373 | function VideoContainer(props: VideoContainerProps) { 374 | const videoRef = useRef(null); 375 | 376 | useEffect(() => { 377 | if (videoRef.current) { 378 | videoRef.current.srcObject = props.stream; 379 | } 380 | }, [props.stream]); 381 | 382 | return ( 383 |
384 | {(props.stream === null || props.loading) && ( 385 | 386 | )} 387 |
399 | ); 400 | } 401 | -------------------------------------------------------------------------------- /demo-react/src/main.tsx: -------------------------------------------------------------------------------- 1 | import { createRoot } from "react-dom/client"; 2 | import App from "./App.tsx"; 3 | 4 | createRoot(document.getElementById("root")!).render( 5 | , 6 | ); 7 | -------------------------------------------------------------------------------- /demo-react/src/util.ts: -------------------------------------------------------------------------------- 1 | import { useCallback, useEffect, useState } from "react"; 2 | 3 | export function useSyncURLWithState( 4 | paramName: string, 5 | initialState: string, 6 | ): [string, (newValue: string) => void] { 7 | // Read initial state from URL on mount 8 | const searchParams = new URLSearchParams(window.location.search); 9 | const initialValueFromURL = searchParams.get(paramName); 10 | if (initialValueFromURL !== null) { 11 | initialState = initialValueFromURL; 12 | } 13 | const [state, setState] = useState(initialState); 14 | 15 | useEffect(() => { 16 | // Listen for changes in the URL (e.g., back/forward button) 17 | const handlePopstate = () => { 18 | const newSearchParams = new URLSearchParams(window.location.search); 19 | const newValueFromURL = newSearchParams.get(paramName); 20 | if (newValueFromURL !== null) { 21 | setState(newValueFromURL); 22 | } else if (initialState !== undefined) { 23 | setState(initialState); 24 | } else { 25 | setState(""); // Or your desired default if no initial state 26 | } 27 | }; 28 | 29 | window.addEventListener("popstate", handlePopstate); 30 | 31 | return () => { 32 | window.removeEventListener("popstate", handlePopstate); 33 | }; 34 | }, [paramName, initialState]); 35 | 36 | const updateState = useCallback((newValue: string) => { 37 | setState(newValue); 38 | const searchParams = new URLSearchParams(window.location.search); 39 | if (newValue) { 40 | searchParams.set(paramName, newValue); 41 | } else { 42 | searchParams.delete(paramName); // Remove if value is empty 43 | } 44 | const newURL = 45 | `${window.location.pathname}?${searchParams.toString()}${window.location.hash}`; 46 | window.history.pushState(null, "", newURL); 47 | }, [paramName]); 48 | 49 | return [state, updateState]; 50 | } 51 | -------------------------------------------------------------------------------- /demo-react/src/vite-env.d.ts: -------------------------------------------------------------------------------- 1 | /// 2 | -------------------------------------------------------------------------------- /demo-react/tsconfig.app.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo", 4 | "target": "ES2020", 5 | "useDefineForClassFields": true, 6 | "lib": ["ES2020", "DOM", "DOM.Iterable"], 7 | "module": "ESNext", 8 | "skipLibCheck": true, 9 | 10 | /* Bundler mode */ 11 | "moduleResolution": "Bundler", 12 | "allowImportingTsExtensions": true, 13 | "isolatedModules": true, 14 | "moduleDetection": "force", 15 | "noEmit": true, 16 | "jsx": "react-jsx", 17 | 18 | /* Linting */ 19 | "strict": true, 20 | "noUnusedLocals": true, 21 | "noUnusedParameters": true, 22 | "noFallthroughCasesInSwitch": true, 23 | "noUncheckedSideEffectImports": true 24 | }, 25 | "include": ["src"] 26 | } 27 | -------------------------------------------------------------------------------- /demo-react/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "files": [], 3 | "references": [ 4 | { 5 | "path": "./tsconfig.app.json" 6 | }, 7 | { 8 | "path": "./tsconfig.node.json" 9 | } 10 | ] 11 | } 12 | -------------------------------------------------------------------------------- /demo-react/tsconfig.node.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo", 4 | "target": "ES2022", 5 | "lib": [ 6 | "ES2023" 7 | ], 8 | "module": "ESNext", 9 | "skipLibCheck": true, 10 | /* Bundler mode */ 11 | "moduleResolution": "Bundler", 12 | "allowImportingTsExtensions": true, 13 | "isolatedModules": true, 14 | "moduleDetection": "force", 15 | "noEmit": true, 16 | /* Linting */ 17 | "strict": true, 18 | "noUnusedLocals": true, 19 | "noUnusedParameters": true, 20 | "noFallthroughCasesInSwitch": true, 21 | "noUncheckedSideEffectImports": true, 22 | "types": [ 23 | "@cloudflare/workers-types" 24 | ] 25 | }, 26 | "include": [ 27 | "vite.config.ts" 28 | ] 29 | } 30 | -------------------------------------------------------------------------------- /demo-react/vite.config.ts: -------------------------------------------------------------------------------- 1 | import { defineConfig, UserConfig } from "vite"; 2 | import react from "@vitejs/plugin-react-swc"; 3 | import { auth } from "@pulsebeam/demo-server"; 4 | 5 | // https://vite.dev/config/ 6 | export default defineConfig(async ({ mode }) => { 7 | const config: UserConfig = { 8 | plugins: [react()], 9 | server: { 10 | proxy: {}, 11 | }, 12 | }; 13 | 14 | if (mode !== "production") { 15 | config.server!.proxy!["/auth"] = { 16 | // https://github.com/angular/angular-cli/issues/26198 17 | target: "http://127.0.0.1:5173", 18 | bypass(req, res) { 19 | // URL requires a base url... 20 | const url = new URL(req.url!, `http://${req.headers.host}`); 21 | if (url.pathname === "/auth") { 22 | try { 23 | const token = auth(url); 24 | res.writeHead(200, { 25 | "Content-Type": "text/plain; charset=utf-8", 26 | }); 27 | res.end(token); 28 | } catch (e) { 29 | res.writeHead(400, { "Content-Type": "text/plain" }); 30 | res.end("Bad Request - groupId and peerId are required"); 31 | } 32 | } 33 | }, 34 | }; 35 | } 36 | 37 | return config; 38 | }); 39 | -------------------------------------------------------------------------------- /demo-react/wrangler.toml: -------------------------------------------------------------------------------- 1 | name = "meet" 2 | pages_build_output_dir = "./dist" 3 | compatibility_flags = [ "nodejs_compat" ] 4 | compatibility_date = "2024-09-23" 5 | 6 | [dev] 7 | ip = "127.0.0.1" 8 | port = 8080 9 | local_protocol = "http" 10 | -------------------------------------------------------------------------------- /demo-server/README.md: -------------------------------------------------------------------------------- 1 | # `demo-server` is an example `node.js` http auth token server 2 | 3 | ### When running our demos locally, PulseBeam convention states: 4 | * Demo will use the local `/auth` server defined here (in `demo-server`) 5 | * Adding `development=true` as a URL parameter will use insecure [development auth](https://pulsebeam.dev/docs/getting-started/quick-start/) 6 | 7 | ### For more information, see [related docs:](https://pulsebeam.dev/docs/guides/token/) 8 | 9 | ### Unfamiliar terms? [See glossary](https://pulsebeam.dev/docs/concepts/terms/) 10 | 11 | ### Our demos: 12 | * Data channel `../demo-cdn`, our [quickstart demo](https://pulsebeam.dev/docs/getting-started/quick-start/) 13 | * Video `../demo-react`, our [video chat demo](https://meet.pulsebeam.dev/) 14 | 15 | ### For questions, [contact us](https://pulsebeam.dev/docs/community-and-support/support/) 16 | 17 | -------------------------------------------------------------------------------- /demo-server/index.d.ts: -------------------------------------------------------------------------------- 1 | export function auth(url: URL): string; 2 | -------------------------------------------------------------------------------- /demo-server/index.js: -------------------------------------------------------------------------------- 1 | import { AccessToken, PeerClaims, PeerPolicy } from "@pulsebeam/server/node"; 2 | 3 | let missingKeysError = false; 4 | const appId = process.env["PULSEBEAM_API_KEY"] || "kid_<...>"; 5 | const appSecret = process.env["PULSEBEAM_API_SECRET"] || "sk_<...>"; 6 | 7 | if (appId === "kid_<...>" || appSecret === "sk_<...>") { 8 | missingKeysError = true; 9 | console.error( 10 | "ERROR: Keys not set see https://pulsebeam.dev/docs/getting-started/quick-start/", 11 | ); 12 | } 13 | 14 | const app = new AccessToken(appId, appSecret); 15 | 16 | export function auth(url) { 17 | if (missingKeysError) throw new Error("Keys are required to generate tokens"); 18 | 19 | const groupId = url.searchParams.get("groupId"); 20 | const peerId = url.searchParams.get("peerId"); 21 | 22 | if (!groupId || !peerId) { 23 | throw new Error("groupId and peerId are required"); 24 | } 25 | 26 | const claims = new PeerClaims(groupId, peerId); 27 | const rule = new PeerPolicy("*", "*"); 28 | claims.setAllowPolicy(rule); 29 | claims.setAllowPolicy(rule); 30 | 31 | const token = app.createToken(claims, 3600); 32 | return token; 33 | } 34 | -------------------------------------------------------------------------------- /demo-server/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@pulsebeam/demo-server", 3 | "version": "1.0.0", 4 | "module": "index.js", 5 | "types": "index.d.ts", 6 | "exports": { 7 | ".": "./index.js" 8 | }, 9 | "type": "module", 10 | "license": "Apache-2.0", 11 | "author": "Lukas Herman support@pulsebeam.dev", 12 | "repository": { 13 | "type": "git", 14 | "url": "https://github.com/PulseBeamDev/pulsebeam-js.git" 15 | }, 16 | "homepage": "https://pulsebeam.dev", 17 | "scripts": {}, 18 | "keywords": [], 19 | "description": "", 20 | "dependencies": { 21 | "@pulsebeam/server": "^0.0.29", 22 | "serve-handler": "^6.1.6" 23 | } 24 | } 25 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "workspaces": [ 3 | "client-web", 4 | "peer", 5 | "demo-react", 6 | "demo-cdn", 7 | "demo-server" 8 | ], 9 | "license": "Apache-2.0", 10 | "author": "Lukas Herman support@pulsebeam.dev", 11 | "repository": { 12 | "type": "git", 13 | "url": "https://github.com/PulseBeamDev/pulsebeam-js.git" 14 | }, 15 | "homepage": "https://pulsebeam.dev", 16 | "dependencies": { 17 | "@playwright/test": "^1.49.1", 18 | "@pulsebeam/peer": "^0.0.17", 19 | "playwright": "^1.49.1", 20 | "ts-node": "^10.9.2" 21 | } 22 | } 23 | -------------------------------------------------------------------------------- /peer/.gitignore: -------------------------------------------------------------------------------- 1 | dist 2 | docs 3 | __tmp.json 4 | 5 | # Logs 6 | logs 7 | *.log 8 | npm-debug.log* 9 | yarn-debug.log* 10 | yarn-error.log* 11 | pnpm-debug.log* 12 | lerna-debug.log* 13 | 14 | node_modules 15 | dist 16 | dist-ssr 17 | *.local 18 | 19 | # Editor directories and files 20 | .vscode/* 21 | !.vscode/extensions.json 22 | .idea 23 | .DS_Store 24 | *.suo 25 | *.ntvs* 26 | *.njsproj 27 | *.sln 28 | *.sw? 29 | -------------------------------------------------------------------------------- /peer/CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # PulseBeam-JS Client SDK 2 | 3 | used to generate @pulsebeam/peer js package 4 | 5 | ## Init project 6 | ```sh 7 | git clone git@github.com:PulseBeamDev/pulsebeam-proto.git 8 | git submodule update --init 9 | npm install 10 | npm run gen 11 | ``` 12 | 13 | ## Update docs 14 | 15 | 1. Update the contents using jsdoc 16 | 2. `deno doc index.ts` to render the changes 17 | 3. `deno doc --lint index.ts` to see missing docs / errors 18 | 4. `deno test --doc` to see errors in code examples 19 | 5. commit and push to jsr 20 | 21 | ## Bump version 22 | 23 | `make bump`: will create a bump commit and tag 24 | `git push origin main && git push origin --tags`: push the commit and tag 25 | 26 | After this, the CI will take over to release everywhere. Use the manual commands as the manual approval. 27 | -------------------------------------------------------------------------------- /peer/Makefile: -------------------------------------------------------------------------------- 1 | VERSION := 0.0.0 2 | 3 | test: 4 | npx vitest run 5 | 6 | bump: 7 | bash bump.bash ${VERSION} 8 | 9 | publish: 10 | npm run publish 11 | -------------------------------------------------------------------------------- /peer/README.md: -------------------------------------------------------------------------------- 1 | # @pulsebeam/peer: WebRTC Peer-to-Peer Communication SDK 2 | 3 | Simplifies real-time application development. Defines signaling protocol for connection establishment, handling media and data transmission, and provides infrastructure. 4 | 5 | ## Features 6 | 7 | - Media & Data Support: Transmit audio, video, and/or data channels within your applications. 8 | - Abstracted Signaling: Handles the exchange of information required to set up WebRTC connections, relieving you of low-level details. 9 | - Automatic Reconnection: Maintains connection stability by automatically re-establishing connections when disruptions occur. 10 | - Opt out of Peer-to-Peer: Can configure to force server-relayed communication. 11 | 12 | ## Roadmap 13 | 14 | The project is in active development, please refer to the [roadmap](https://github.com/PulseBeamDev/pulsebeam-js/issues/6) to track our major milestones. 15 | 16 | ## Status 17 | 18 | > [!WARNING] 19 | > This SDK is currently in **Developer Preview**. During this phase: 20 | > - APIs are subject to breaking changes 21 | > - Stability issues may occur 22 | > - Core functionality is still being validated 23 | > 24 | > **We value your input!** 25 | > Report bugs, suggest improvements, or collaborate directly with our team: 26 | > 27 | > • [Create GitHub Issues](https://github.com/PulseBeamDev/pulsebeam-js/issues) 28 | > • [Join PulseBeam Developer Discord](https://discord.gg/Bhd3t9afuB) 29 | 30 | ## Installation 31 | 32 | Install and import the package using npm, deno, or yarn: 33 | 34 | ### Use with npm 35 | 36 | Add Package 37 | 38 | `npm i @pulsebeam/peer` 39 | 40 | Import symbol 41 | 42 | `import * as peer from "@pulsebeam/peer";` 43 | 44 | ### Use with Yarn 45 | 46 | Add Package 47 | 48 | `yarn add @pulsebeam/peer` 49 | 50 | Import symbol 51 | 52 | `import * as peer from "@pulsebeam/peer";` 53 | 54 | 55 | ## Usage 56 | 57 | Here's an example demonstrating how to use @pulsebeam/peer to establish a peer-to-peer connection: 58 | 59 | ```ts 60 | import { Peer, createPeer } from "@pulsebeam/peer"; 61 | 62 | // Obtain an authentication token (implementation specific) 63 | const authResponse = await fetch("/auth"); 64 | const { groupId, token } = await authResponse.json(); 65 | 66 | // Create a Peer instance 67 | const peer = await createPeer({ token }); 68 | 69 | peer.onsession = (session) => { 70 | session.ontrack = ({ streams }) => console.log("New media stream:", streams); 71 | session.ondatachannel = (event) => console.log("Data channel:", event.channel); 72 | session.onconnectionstatechange = () => console.log("Connection state changed"); 73 | }; 74 | 75 | // Start Alice's availability. Connect to our signaling servers 76 | peer.start(); 77 | 78 | // Connect to bob 79 | const abortController = new AbortController(); 80 | await peer.connect(groupId, "bob", abortController.signal); 81 | ``` 82 | 83 | This example retrieves an authentication token (implementation details will vary depending on your setup), creates a Peer instance, and defines event handlers for receiving media streams, data channels, and connection state changes (optional). Finally, it starts connection attempts and connects to a specific peer identified by its ID within the group. 84 | 85 | ## Documentation 86 | 87 | For documentation, API keys, and usage scenarios, please refer to the official PulseBeam documentation: 88 | 89 | * Guide: https://pulsebeam.dev/docs 90 | * Client SDK Reference: https://jsr.io/@pulsebeam/peer 91 | * Server SDK Reference: https://jsr.io/@pulsebeam/server 92 | 93 | ## Semantic Versioning 94 | 95 | This project adheres to [Semantic Versioning 2.0.0](https://semver.org/). 96 | 97 | * **MAJOR version (X.y.z):** Incompatible API changes. 98 | * **MINOR version (x.Y.z):** Functionality added in a backwards compatible manner. 99 | * **PATCH version (x.y.Z):** Backwards compatible bug fixes. 100 | 101 | ## WebRTC Resources 102 | 103 | For a deeper understanding of WebRTC concepts, consult the official WebRTC documentation: 104 | 105 | * https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API 106 | 107 | ## Related Links 108 | 109 | |Name|Link| 110 | |-|-| 111 | |Client SDK|https://github.com/PulseBeamDev/pulsebeam-js| 112 | |Server SDK|https://github.com/PulseBeamDev/pulsebeam-core| 113 | |FOSS Server|https://github.com/PulseBeamDev/pulsebeam-server-foss| 114 | |Signaling Protocol|https://github.com/PulseBeamDev/pulsebeam-proto| 115 | |Documentation|https://github.com/PulseBeamDev/docs| 116 | |PulseBeam Cloud|https://cloud.pulsebeam.dev| 117 | 118 | -------------------------------------------------------------------------------- /peer/bump.bash: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # a script that maintains both jsr and npm package versions to be aligned with git tags 4 | set -e 5 | 6 | tmp=__tmp.json 7 | version=${1} 8 | version_tag="v${version}" 9 | 10 | if ! echo ${version} | grep -Eo '^[0-9]{1,}.[0-9]{1,}.[0-9]{1,}'; then 11 | echo "VERSION must be in semver format" 12 | exit 1 13 | fi 14 | 15 | if ! [[ "$(git branch --show-current)" == "main" ]]; then 16 | echo "bumping version has to be based on main" 17 | exit 1 18 | fi 19 | 20 | if ! git diff-index --quiet HEAD --; then 21 | echo "Error: Git working directory is dirty. Please commit or stash your changes before proceeding." 22 | exit 1 23 | fi 24 | 25 | git fetch origin 26 | git log origin/main..HEAD 27 | 28 | read -p "Are you sure to bump version to ${version}? " -n 1 -r 29 | echo # (optional) move to a new line 30 | if ! [[ $REPLY =~ ^[Yy]$ ]]; then 31 | exit 1 32 | fi 33 | 34 | jq ".version = \"${version}\"" package.json >${tmp} 35 | mv ${tmp} package.json 36 | 37 | jq ".version = \"${version}\"" jsr.json >${tmp} 38 | mv ${tmp} jsr.json 39 | cd .. && npm install 40 | 41 | git add . 42 | git commit -m "[peer] bump to ${version}" 43 | git tag ${version_tag} 44 | 45 | echo "version bump has been commited and tagged" 46 | git push origin main 47 | git push origin refs/tags/${version_tag} 48 | -------------------------------------------------------------------------------- /peer/generate.bash: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e 3 | 4 | protoc --ts_out=src --experimental_allow_proto3_optional --ts_opt=client_generic --proto_path proto/v1 ./proto/v1/signaling.proto 5 | node ./scripts/patch.cjs 6 | # sed -i '1s;^;// @ts-nocheck\n;' ./src/google/protobuf/timestamp.ts 7 | -------------------------------------------------------------------------------- /peer/index.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | PulseBeam 9 | 10 | 11 | 13 | 14 | 15 | 16 | 17 |
18 |

Chat

19 |
20 |
21 | 22 | 30 | 31 | 32 | 33 | 34 | 35 | -------------------------------------------------------------------------------- /peer/jsr.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@pulsebeam/peer", 3 | "version": "0.1.0-rc.2", 4 | "exports": "./src/index.ts", 5 | "license": "Apache-2.0", 6 | "author": "Lukas Herman support@pulsebeam.dev", 7 | "repository": { 8 | "type": "git", 9 | "url": "https://github.com/PulseBeamDev/pulsebeam-js.git" 10 | }, 11 | "homepage": "https://pulsebeam.dev", 12 | "publish": { 13 | "exclude": [ 14 | "proto", 15 | "scripts", 16 | "dist" 17 | ] 18 | } 19 | } 20 | -------------------------------------------------------------------------------- /peer/main.ts: -------------------------------------------------------------------------------- 1 | import { createPeer, PeerStore } from "./src/index.ts"; 2 | 3 | (async () => { 4 | const urlParams = new URLSearchParams(window.location.search); 5 | const baseUrl = urlParams.get("baseUrl"); 6 | const groupId = urlParams.get("groupId") || ""; 7 | const peerId = urlParams.get("peerId") || ""; 8 | 9 | // See https://pulsebeam.dev/docs/guides/token/#example-nodejs-http-server 10 | // For explanation of this token-serving method 11 | const resp = await fetch( 12 | `/auth?groupId=${groupId}&peerId=${peerId}`, 13 | ); 14 | const token = await resp.text(); 15 | 16 | const peer = await createPeer({ 17 | baseUrl: baseUrl || undefined, 18 | token, 19 | }); 20 | const store = new PeerStore(peer); 21 | 22 | const textDOM = document.getElementById("text")! as HTMLInputElement; 23 | const formDOM = document.getElementById("form")! as HTMLFormElement; 24 | const containerDOM = document.getElementById("container")!; 25 | 26 | formDOM.onsubmit = (e) => { 27 | e.preventDefault(); 28 | 29 | const key = `${new Date().toISOString()} (${peerId})`; 30 | store.$kv.setKey(key, textDOM.value); 31 | textDOM.value = ""; 32 | }; 33 | 34 | store.$kv.listen(() => { 35 | // TODO: this is naive, this can be done more efficiently with a binary heap or bst. 36 | const snapshot = store.$kv.get(); 37 | const messages = Object.entries(snapshot); 38 | 39 | messages.sort((a, b) => a[0].localeCompare(b[0])); 40 | containerDOM.innerHTML = ""; 41 | for (const [dt, msg] of messages) { 42 | const msgDOM = document.createElement("p"); 43 | msgDOM.textContent = `${dt}: ${msg}`; 44 | containerDOM.appendChild(msgDOM); 45 | } 46 | }); 47 | store.start(); 48 | })(); 49 | -------------------------------------------------------------------------------- /peer/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@pulsebeam/peer", 3 | "version": "0.1.0-rc.2", 4 | "type": "module", 5 | "files": [ 6 | "dist" 7 | ], 8 | "main": "./dist/index.cjs", 9 | "module": "dist/index.mjs", 10 | "types": "dist/index.d.mts", 11 | "exports": { 12 | "import": { 13 | "types": "./dist/index.d.ts", 14 | "import": "./dist/index.js" 15 | }, 16 | "require": { 17 | "types": "./dist/index.d.cts", 18 | "require": "./dist/index.cjs" 19 | } 20 | }, 21 | "scripts": { 22 | "gen": "bash ./generate.bash", 23 | "dev": "vite", 24 | "build": "tsup src/index.ts --format esm,cjs --dts --minify", 25 | "clean": "rm -rf dist", 26 | "test": "vitest", 27 | "preview": "vite preview", 28 | "show:docs": "npx deno doc --html index.ts && python -m http.server -d docs/", 29 | "publish": "jsr publish --allow-slow-types" 30 | }, 31 | "keywords": [ 32 | "typescript", 33 | "library", 34 | "browser" 35 | ], 36 | "author": "Lukas Herman support@pulsebeam.dev", 37 | "repository": { 38 | "type": "git", 39 | "url": "https://github.com/PulseBeamDev/pulsebeam-js.git" 40 | }, 41 | "homepage": "https://pulsebeam.dev", 42 | "license": "Apache-2.0", 43 | "dependencies": { 44 | "@protobuf-ts/grpcweb-transport": "^2.9.5", 45 | "@protobuf-ts/runtime": "^2.9.4", 46 | "@protobuf-ts/runtime-rpc": "^2.9.4", 47 | "jwt-decode": "^4.0.0", 48 | "nanostores": "^0.11.4" 49 | }, 50 | "devDependencies": { 51 | "@protobuf-ts/plugin": "^2.9.4", 52 | "jsr": "^0.13.2", 53 | "protoc-gen-ts": "^0.8.7", 54 | "tsup": "^8.4.0", 55 | "typescript": "^5.7.2", 56 | "vite": "^6.2.0", 57 | "vitest": "^3.0.5", 58 | "webrtc-adapter": "^9.0.1" 59 | } 60 | } 61 | -------------------------------------------------------------------------------- /peer/scripts/patch.cjs: -------------------------------------------------------------------------------- 1 | const { promises: fs } = require('fs'); 2 | const path = require('path'); 3 | 4 | const protoRoot = path.join(__dirname, ".."); 5 | 6 | async function patchProtoFiles() { 7 | const walk = async function* (dir, { exts, includeFiles }) { 8 | const entries = await fs.readdir(dir, { withFileTypes: true }); 9 | for (const entry of entries) { 10 | const res = { 11 | path: path.join(dir, entry.name), 12 | name: entry.name, 13 | isFile: entry.isFile(), 14 | isDirectory: entry.isDirectory(), 15 | isSymlink: entry.isSymbolicLink(), 16 | }; 17 | if (res.isDirectory) { 18 | yield* walk(res.path, { exts, includeFiles }); 19 | } else if ( 20 | (includeFiles && res.isFile) || 21 | (exts && exts.includes(path.extname(res.name).slice(1))) 22 | ) { 23 | yield res; 24 | } 25 | } 26 | }; 27 | 28 | for await (const entry of walk(protoRoot, { exts: ['ts'], includeFiles: true })) { 29 | const filePath = entry.path; 30 | 31 | // Read the file content 32 | let content = await fs.readFile(filePath, 'utf-8'); 33 | 34 | // Perform the replacement 35 | content = content 36 | .split('\n') 37 | .map((line) => 38 | line.replace(/^(import .+? from ["']\..+?)(?; 84 | let audioReceiverStats: RTCReceiverStats | undefined; 85 | let videoReceiverStats: RTCReceiverStats | undefined; 86 | let rtt: number | undefined; 87 | let peerConnectionStats: RTCPeerConnectionStats | undefined; 88 | 89 | for (const stat of statsIter) { 90 | if (stat.type === "inbound-rtp" || stat.type === "rtp-receiver") { 91 | // https://developer.mozilla.org/en-US/docs/Web/API/RTCInboundRtpStreamStats 92 | const receiverStat = stat as RTCReceiverStats; 93 | if (receiverStat.kind === "audio") { 94 | audioReceiverStats = receiverStat; 95 | } else { 96 | videoReceiverStats = receiverStat; 97 | } 98 | } else if (stat.type === "candidate-pair") { 99 | // https://developer.mozilla.org/en-US/docs/Web/API/RTCIceCandidatePairStats 100 | const candidatePairStat = stat as RTCIceCandidatePairStats; 101 | // prioritize remote-inbound-rtp rtt 102 | if (candidatePairStat.state === "succeeded" && !rtt) { 103 | rtt = candidatePairStat.currentRoundTripTime; 104 | } 105 | } else if (stat.type === "peer-connection") { 106 | peerConnectionStats = stat as RTCPeerConnectionStats; 107 | } else if (stat.type === "remote-inbound-rtp") { 108 | // There are 2 cases when we need this: 109 | // 1. Fallback for Firefox's missing ICE RTT support 110 | // 2. Faster RTT calculation as it is used in RTP streams 111 | // 112 | // If there's only data channel without media streams, Firefox won't generate RTT. 113 | const remoteInboundStat = stat as RTCRemoteInboundRtpStreamStats; 114 | rtt = remoteInboundStat.roundTripTime; 115 | } 116 | } 117 | 118 | if ( 119 | peerConnectionStats && peerConnectionStats.iceConnectionState && 120 | !["connected", "completed"].includes(peerConnectionStats.iceConnectionState) 121 | ) { 122 | return null; 123 | } 124 | 125 | const quality: QualityStats = {}; 126 | 127 | let audioQuality = 100; 128 | if (audioReceiverStats) { 129 | const packetsLost = audioReceiverStats.packetsLost ?? 0; 130 | const packetsReceived = audioReceiverStats.packetsReceived ?? 0; 131 | const audioPacketLossRatio = packetsReceived > 0 132 | ? packetsLost / packetsReceived 133 | : 0; 134 | const audioPacketLossScore = Math.max( 135 | 0, 136 | 100 - (audioPacketLossRatio * 100), 137 | ); 138 | const audioJitter = audioReceiverStats.jitter ?? 0; 139 | const audioJitterScore = audioJitter < 0.02 140 | ? 100 141 | : (audioJitter < 0.1 ? 70 : 30); 142 | audioQuality = (audioPacketLossScore + audioJitterScore) / 2; 143 | } 144 | 145 | let videoQuality = 100; 146 | if (videoReceiverStats) { 147 | const packetsLost = videoReceiverStats.packetsLost ?? 0; 148 | const packetsReceived = videoReceiverStats.packetsReceived ?? 0; 149 | const videoPacketLossRatio = packetsReceived > 0 150 | ? packetsLost / packetsReceived 151 | : 0; 152 | const videoPacketLossScore = Math.max( 153 | 0, 154 | 100 - (videoPacketLossRatio * 100), 155 | ); 156 | const videoJitter = videoReceiverStats.jitter ?? 0; 157 | const videoJitterScore = videoJitter < 0.02 158 | ? 100 159 | : (videoJitter < 0.1 ? 70 : 30); 160 | videoQuality = (videoPacketLossScore + videoJitterScore) / 2; 161 | } 162 | 163 | let latencyScore = 80; 164 | if (!!rtt) { 165 | // second to microseconds 166 | quality.rttUs = BigInt(Math.trunc(rtt * 1e6)); 167 | latencyScore = rtt < 0.1 ? 100 : (rtt < 0.3 ? 80 : (rtt < 0.5 ? 60 : 40)); 168 | } 169 | 170 | const overallQuality = Math.round( 171 | (videoQuality * 0.5) + (audioQuality * 0.3) + (latencyScore * 0.2), 172 | ); 173 | const qualityScore = Math.max(0, Math.min(100, overallQuality)); 174 | quality.qualityScore = BigInt(qualityScore); 175 | 176 | return quality; 177 | } 178 | 179 | export function now(): bigint { 180 | // https://developer.mozilla.org/en-US/docs/Web/API/Performance_API/High_precision_timing#time_origins 181 | // the following combination prevents clock skewing or clock going backward due to users 182 | // changing their system clocks. 183 | // but, timeOrigin starts skewing from the UTC overtime, https://dev.to/noamr/when-a-millisecond-is-not-a-millisecond-3h6 184 | // return BigInt( 185 | // Math.floor(performance.timeOrigin + performance.now()) * 1000, 186 | // ); 187 | return BigInt(Date.now() * 1000); 188 | } 189 | -------------------------------------------------------------------------------- /peer/src/index.ts: -------------------------------------------------------------------------------- 1 | import adapter from "webrtc-adapter"; 2 | export * from "./peer.ts"; 3 | export * from "./store.ts"; 4 | 5 | adapter.disableLog(false); 6 | adapter.disableWarnings(false); 7 | console.log("UA: ", navigator.userAgent); 8 | console.log( 9 | "webrtc-adapter is enabled", 10 | JSON.stringify( 11 | { shim: adapter.browserShim, version: adapter.browserDetails }, 12 | null, 13 | 2, 14 | ), 15 | ); 16 | -------------------------------------------------------------------------------- /peer/src/logger.test.ts: -------------------------------------------------------------------------------- 1 | import { describe, it } from "vitest"; 2 | import { Logger, PRETTY_LOG_SINK } from "./logger.ts"; 3 | 4 | describe("logger", () => { 5 | it("should stop recursing", () => { 6 | const logger = new Logger("base", {}, PRETTY_LOG_SINK); 7 | const obj1: Record = { "a": null }; 8 | const obj2 = { b: obj1 }; 9 | obj1.a = obj2; 10 | 11 | logger.info("test", obj1); 12 | }); 13 | }); 14 | -------------------------------------------------------------------------------- /peer/src/logger.ts: -------------------------------------------------------------------------------- 1 | type LogObj = Record; 2 | type LogHandler = (_obj: LogObj) => void; 3 | type LogSink = { 4 | "DEBUG": LogHandler; 5 | "INFO": LogHandler; 6 | "WARN": LogHandler; 7 | "ERROR": LogHandler; 8 | }; 9 | 10 | export const DEFAULT_LOG_SINK: LogSink = { 11 | DEBUG: console.debug, 12 | INFO: console.info, 13 | WARN: console.warn, 14 | ERROR: console.error, 15 | }; 16 | 17 | // inspired by toml format, https://toml.io/en/ 18 | // the main difference is that the fields are appended on the same line 19 | // to optimize readability in console. 20 | export const PRETTY_LOG_SINK: LogSink = { 21 | DEBUG: (o) => console.debug(pretty(o)), 22 | INFO: (o) => console.info(pretty(o)), 23 | WARN: (o) => console.warn(pretty(o)), 24 | ERROR: (o) => console.error(pretty(o)), 25 | }; 26 | 27 | export function flatten( 28 | obj: LogObj, 29 | pairs: Record, 30 | parentKey = "root", 31 | visited = new Set(), 32 | ) { 33 | const sep = "."; 34 | if (visited.has(obj)) return; // Stop if already visited 35 | visited.add(obj); 36 | 37 | for (const key in obj) { 38 | if (typeof obj[key] === "object" && obj[key] !== null) { 39 | const newKey = parentKey + sep + key; 40 | flatten(obj[key] as LogObj, pairs, newKey, visited); 41 | } else { 42 | const p = pairs[parentKey] || []; 43 | p.push(`${key}=${obj[key]}`); 44 | pairs[parentKey] = p; 45 | } 46 | } 47 | } 48 | 49 | export function pretty(obj: LogObj) { 50 | const pairs: Record = {}; 51 | flatten(obj, pairs); 52 | 53 | const lines: string[] = []; 54 | for (const k in pairs) { 55 | lines.push(`[${k}] ${pairs[k].join(" ")}`); 56 | } 57 | return lines.join("\n"); 58 | } 59 | 60 | export class Logger { 61 | private readonly obj: LogObj; 62 | private readonly sink: LogSink; 63 | constructor(public readonly name: string, obj?: LogObj, sink?: LogSink) { 64 | if (!obj) obj = {}; 65 | if (!sink) sink = DEFAULT_LOG_SINK; 66 | this.sink = sink; 67 | this.obj = { ...obj, name }; 68 | } 69 | 70 | private log( 71 | handler: LogHandler, 72 | message: string, 73 | obj?: LogObj, 74 | ): void { 75 | const o = obj || {}; 76 | handler({ 77 | ts: Date.now(), 78 | message, 79 | ...this.obj, 80 | ...o, 81 | }); 82 | } 83 | 84 | debug(message: string, obj?: LogObj): void { 85 | this.log(this.sink.DEBUG, message, obj); 86 | } 87 | 88 | info(message: string, obj?: LogObj): void { 89 | this.log(this.sink.INFO, message, obj); 90 | } 91 | 92 | warn(message: string, obj?: LogObj): void { 93 | this.log(this.sink.WARN, message, obj); 94 | } 95 | 96 | error(message: string, obj?: LogObj): void { 97 | this.log(this.sink.ERROR, message, obj); 98 | } 99 | 100 | sub(name: string, obj?: LogObj): Logger { 101 | if (!obj) obj = {}; 102 | return new Logger( 103 | this.name + "." + name, 104 | { ...this.obj, ...obj }, 105 | this.sink, 106 | ); 107 | } 108 | } 109 | -------------------------------------------------------------------------------- /peer/src/peer.ts: -------------------------------------------------------------------------------- 1 | import { type ISignalingClient, SignalingClient } from "./signaling.client.ts"; 2 | import { Transport } from "./transport.ts"; 3 | import type { 4 | AnalyticsReport, 5 | AnalyticsReportReq, 6 | PeerInfo, 7 | } from "./signaling.ts"; 8 | import { Logger, PRETTY_LOG_SINK } from "./logger.ts"; 9 | import { Session } from "./session.ts"; 10 | import { RpcError, RpcOptions, UnaryCall } from "@protobuf-ts/runtime-rpc"; 11 | import { 12 | GrpcStatusCode, 13 | GrpcWebFetchTransport, 14 | } from "@protobuf-ts/grpcweb-transport"; 15 | import { asleep, retry } from "./util.ts"; 16 | import { jwtDecode } from "jwt-decode"; 17 | 18 | export type { PeerInfo } from "./signaling.ts"; 19 | 20 | const ANALYTICS_POLL_INTERVAL_MS = 60_000; 21 | 22 | /** 23 | * Streamline real-time application development.`@pulsebeam/peer` abstracts 24 | * networking, connection management, and signaling for applications. Built on 25 | * WebRTC. PulseBeam handles peer-to-peer communication, media/data transmission, 26 | * and provides infrastructure. 27 | * 28 | * A JavaScript SDK for creating real-time applications with WebRTC. 29 | * 30 | * # Features 31 | * - Flexible connection modes: peer-to-peer or server-relayed. 32 | * - Support for media (audio/video) and data channels. 33 | * - Abstracted signaling for establishing WebRTC connections. 34 | * - Auto-reconnect during disruptions or dropped connections. 35 | * 36 | * For more on PulseBeam, see our docs and quickstart guide: 37 | * {@link https://pulsebeam.dev/docs/getting-started/} 38 | * 39 | * For more on WebRTC, see the official documentation: 40 | * {@link https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API} 41 | * 42 | * # Example Usage 43 | * 44 | * Request an authentication token, initialize a peer instance, and establish a connection: 45 | * 46 | * ```ts 47 | * import { Peer, createPeer } from "@pulsebeam/peer"; 48 | * 49 | * // Step 1: Obtain an auth token 50 | * const authResponse = await fetch("/auth"); 51 | * const { groupId, peerId, token } = await authResponse.json(); 52 | * 53 | * // Step 2: Create a Peer instance 54 | * const peer = await createPeer({ groupId, peerId, token }); 55 | * 56 | * peer.onsession = (session) => { 57 | * session.ontrack = ({ streams }) => console.log("New media stream:", streams); 58 | * session.ondatachannel = (event) => console.log("Data channel:", event.channel); 59 | * session.onconnectionstatechange = () => console.log("Connection state changed"); 60 | * }; 61 | * 62 | * // Step 3: Connect to another peer 63 | * peer.start(); 64 | * 65 | * const abortController = new AbortController(); 66 | * await peer.connect(groupId, "other-peer-id", abortController.signal); 67 | * ``` 68 | * 69 | * This module provides a framework for building WebRTC applications while 70 | * leaving room for custom implementation details. 71 | * 72 | * @module 73 | */ 74 | 75 | const BASE_URL = "https://cloud.pulsebeam.dev/grpc"; 76 | 77 | /** 78 | * A high-level API for managing the peer-to-peer WebRTC connection. Provides 79 | * access to lower-level {@link RTCPeerConnection} functionality. Including 80 | * access to underlying media tracks, data channels, and connection state. 81 | * 82 | * Usage: 83 | * @example `peer.onsession = (session) => {console.log(session.other.peerId)};` 84 | */ 85 | export interface ISession { 86 | /** 87 | * Adds a media track to the connection. Typically used for sending audio or video. 88 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/addTrack} 89 | * @returns {RTCRtpSender} 90 | */ 91 | addTrack(...args: Parameters): RTCRtpSender; 92 | 93 | /** 94 | * Removes a media track from the connection. Useful for stopping 95 | * transmission of a specific track. 96 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/removeTrack} 97 | * @returns {void} 98 | */ 99 | removeTrack(...args: Parameters): void; 100 | 101 | /** 102 | * Creates a {@link RTCDataChannel} on the connection for arbitrary data transfer. 103 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createDataChannel} 104 | */ 105 | createDataChannel( 106 | ...args: Parameters 107 | ): RTCDataChannel; 108 | 109 | /** 110 | * Retrieves the current connection state of the underlying RTCPeerConnection 111 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionState} 112 | * @returns {RTCPeerConnectionState} 113 | */ 114 | get connectionState(): RTCPeerConnectionState; 115 | 116 | /** 117 | * Callback triggered when a {@link RTCDataChannel} is created or received. 118 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/ondatachannel} 119 | * @example ```peer.onsession = (session) => { 120 | * session.ondatachannel = (event) => { 121 | * const channel = event.channel; 122 | * channel.onmessage = (e) => console.log("Received message:", e.data); 123 | * };``` 124 | */ 125 | ondatachannel: RTCPeerConnection["ondatachannel"]; 126 | 127 | /** 128 | * Callback triggered when the connection state changes. 129 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/onconnectionstatechange} 130 | */ 131 | onconnectionstatechange: RTCPeerConnection["onconnectionstatechange"]; 132 | 133 | /** 134 | * Callback invoked when a new media track is added to the connection. 135 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/ontrack} 136 | */ 137 | ontrack: RTCPeerConnection["ontrack"]; 138 | 139 | /** 140 | * Closes the session, aborting all pending tasks, and cleaning up resources. 141 | * Publishes events and logs about the closure. 142 | * @param {string} [reason] - (optional) A reason for closing the session. 143 | * @returns {void} 144 | * @example `mysession.close("Session ended by user");` 145 | */ 146 | close(reason?: string): void; 147 | 148 | // Below is PulseBeam specific functionality. Unrelated to 149 | // the underlying RTCPeerConnection 150 | 151 | /** 152 | * Retrieves the identifier of the other peer in the connection. 153 | * @returns {PeerInfo} The peer identity of the connected peer. Valid UTF-8 string of 1-16 characters. 154 | * @example ```console.log(`Connected to peer: ${session.other.peerId()}`);``` 155 | */ 156 | get other(): PeerInfo; 157 | } 158 | 159 | /** 160 | * Intended to be used by for internal and advanced usecases. 161 | * Options used to configure a Peer. 162 | * @interface PeerOptionsFull 163 | * @example``` 164 | * const options: PeerOptionsFull = { 165 | * groupId: "group-123", // Valid UTF-8 strings of 1-16 characters. 166 | * peerId: "peer-456", // Valid UTF-8 strings of 1-16 characters. 167 | * token: "eyJhbGc...49nLmBCg" 168 | * };``` 169 | */ 170 | export interface PeerOptionsFull { 171 | /** 172 | * Identifier for the group which the peer belongs to. Must be a valid UTF-8 173 | * string of 1-16 characters. 174 | * @type {string} groupId 175 | */ 176 | groupId: string; 177 | 178 | /** 179 | * Identifier for the peer. Must be a valid UTF-8 string of 1-16 characters. 180 | * @type {string} peerId 181 | */ 182 | peerId: string; 183 | 184 | /** 185 | * PulseBeam authentication token for the peer. JWT token generated by `jsr:@pulsebeam/server` 186 | * @type {string} token 187 | */ 188 | token: string; 189 | 190 | /** 191 | * By default, client analytics is enabled. To opt out, set this field to true. 192 | * @type {boolean} disableAnalytics 193 | */ 194 | disableAnalytics?: boolean; 195 | 196 | /** 197 | * (Optional) Base URL for API calls. Defaults to using our servers: "https://cloud.pulsebeam.dev/twirp". 198 | * @type {string | undefined} [baseUrl] 199 | */ 200 | baseUrl?: string; 201 | 202 | /** 203 | * (Optional) If true, enforces relay-only connections, such as those passed through a TURN server. Defaults to allowing all connection types (such as direct peer to peer). For more details see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#icetransportpolicy} 204 | * @type {boolean | undefined} [forceRelay] 205 | */ 206 | forceRelay?: boolean; 207 | 208 | /** 209 | * (Optional) Add Ice Servers. Defaults to using our servers. For more details see {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/RTCPeerConnection#iceservers} 210 | * @type {RTCIceServer[] | undefined} [iceServers] 211 | */ 212 | iceServers?: RTCIceServer[]; 213 | } 214 | 215 | /** 216 | * Options used to configure a Peer. See {@link PeerOptionsFull} for properties. 217 | * @interface PeerOptions 218 | * @example``` 219 | * const options: PeerOptions = { 220 | * token: "eyJhbGc...49nLmBCg" // fetch token 221 | * };``` 222 | */ 223 | export type PeerOptions = Omit; 224 | 225 | /** 226 | * Represents the possible states for a Peer. 227 | * 228 | * @readonly 229 | * @enum {string} 230 | * Possible values: 231 | * - `"new"`: The peer has been created. 232 | * - `"closed"`: The peer has been closed. 233 | */ 234 | export type PeerState = "new" | "closed"; 235 | 236 | /** 237 | * Peer is a mediator for signaling, connecting, and managing sessions. 238 | */ 239 | export class Peer { 240 | private transport: Transport; 241 | private readonly logger: Logger; 242 | private _sessions: Session[]; 243 | private _state: PeerState; 244 | 245 | /** 246 | * Callback invoked when a new session is established. 247 | * @param _s Session object 248 | */ 249 | public onsession = (_s: ISession) => {}; 250 | /** 251 | * Callback invoked when the peer’s state changes. 252 | */ 253 | public onstatechange = () => {}; 254 | /** 255 | * Identifier for the peer. Valid UTF-8 string of 1-16 characters. 256 | */ 257 | public readonly peerId: string; 258 | 259 | /** 260 | * Construct a Peer. Helper available: see {@link createPeer} function 261 | * @param logger Logger instance for logging events. 262 | * @param client Tunnel client for signaling. 263 | * @param opts Configuration options for the peer. 264 | * @param isRecoverable Function to determine if an error is recoverable. 265 | */ 266 | constructor( 267 | logger: Logger, 268 | client: ISignalingClient, 269 | private readonly opts: PeerOptionsFull, 270 | isRecoverable: (_err: unknown) => boolean, 271 | ) { 272 | this.peerId = opts.peerId; 273 | this.logger = logger.sub("peer", { peerId: this.peerId }); 274 | this._sessions = []; 275 | this._state = "new"; 276 | 277 | const rtcConfig: RTCConfiguration = { 278 | bundlePolicy: "balanced", 279 | iceTransportPolicy: !!opts.forceRelay ? "relay" : "all", 280 | iceCandidatePoolSize: 0, 281 | iceServers: opts.iceServers, 282 | }; 283 | this.transport = new Transport(client, { 284 | enableDiscovery: false, 285 | groupId: opts.groupId, 286 | peerId: opts.peerId, 287 | logger: this.logger, 288 | isRecoverable, 289 | }); 290 | this.transport.onstream = (s) => { 291 | const sess = new Session(s, rtcConfig); 292 | this._sessions.push(sess); 293 | this.onsession(sess); 294 | }; 295 | this.transport.onclosed = () => { 296 | this.close(); 297 | }; 298 | } 299 | 300 | get sessions(): Session[] { 301 | // lazily remove closed sessions. This is to maintain session list without listening to 302 | // each session's event. 303 | this._sessions = this._sessions.filter((s) => 304 | s.connectionState != "closed" 305 | ); 306 | return [...this._sessions]; 307 | } 308 | 309 | /** 310 | * Starts the peer, making it ready to establish connections. 311 | * Peers must be started before a connection can occur. 312 | * 313 | * @returns {void} 314 | * @throws {Error} When the peer was previously closed. 315 | */ 316 | start() { 317 | if (this._state === "closed") throw new Error("peer is already closed"); 318 | this.transport.listen(); 319 | this.analyticsLoop(); 320 | } 321 | 322 | async analyticsLoop() { 323 | while (this.state != "closed") { 324 | const reports: AnalyticsReport[] = []; 325 | for (const sess of this.sessions) { 326 | const metrics = await sess.collectMetrics(); 327 | reports.push(metrics); 328 | } 329 | 330 | const request: AnalyticsReportReq = { reports }; 331 | 332 | const analyticsEnabled = this.opts.disableAnalytics == undefined || 333 | this.opts.disableAnalytics === false; 334 | if (analyticsEnabled) { 335 | this.transport.reportAnalytics(request); 336 | } 337 | 338 | await asleep(ANALYTICS_POLL_INTERVAL_MS); 339 | } 340 | } 341 | 342 | /** 343 | * Closes the peer. Releases associated resources. 344 | * Signals to the AbortController passed to connect if connect was called. 345 | * 346 | * @async 347 | * @returns {Promise} Resolves when the peer has been closed. 348 | */ 349 | async close() { 350 | this._sessions = []; 351 | await this.transport.close(); 352 | this.setState("closed"); 353 | } 354 | 355 | /** 356 | * Establishes a connection with another peer in the specified group. 357 | * Peer should be started before calling connect. 358 | * 359 | * Check the log output for troubleshooting information. 360 | * 361 | * @async 362 | * @param {string} otherGroupId The ID of the group the other peer belongs to. 363 | * Valid UTF-8 string of 1-16 characters. 364 | * @param {string} otherPeerId The ID of the peer you want to connect to. 365 | * Valid UTF-8 string of 1-16 characters. 366 | * @param {AbortSignal} signal Handle cancellations or cancel the connection attempt. 367 | * @returns {Promise} Resolves when the connection has been established, 368 | * an unrecoverable error (e.g., network connection issues, internal errors) occurs, 369 | * or the maximum retry attempts are reached. 370 | */ 371 | connect( 372 | otherGroupId: string, 373 | otherPeerId: string, 374 | signal: AbortSignal, 375 | ): Promise { 376 | return this.transport.connect(otherGroupId, otherPeerId, signal); 377 | } 378 | 379 | /** 380 | * Gets the current state of the peer. For state info see {@link PeerState} 381 | * @returns {PeerState} The current state of the peer 382 | */ 383 | get state(): PeerState { 384 | return this._state; 385 | } 386 | 387 | /** internal @private */ 388 | private setState(s: PeerState): void { 389 | if (s === this._state) return; 390 | 391 | this._state = s; 392 | this.onstatechange(); 393 | } 394 | } 395 | 396 | const GRPCWEB_FATAL_ERRORS: string[] = [ 397 | GrpcStatusCode[GrpcStatusCode.PERMISSION_DENIED], 398 | GrpcStatusCode[GrpcStatusCode.INVALID_ARGUMENT], 399 | GrpcStatusCode[GrpcStatusCode.ABORTED], 400 | GrpcStatusCode[GrpcStatusCode.NOT_FOUND], 401 | GrpcStatusCode[GrpcStatusCode.UNAUTHENTICATED], 402 | ]; 403 | 404 | function isRecoverable(err: unknown): boolean { 405 | if (!(err instanceof Error)) { 406 | return false; 407 | } 408 | 409 | if (!(err instanceof RpcError)) { 410 | return true; 411 | } 412 | 413 | return !GRPCWEB_FATAL_ERRORS.includes(err.code); 414 | } 415 | 416 | interface JwtClaims { 417 | gid: string; 418 | pid: string; 419 | } 420 | 421 | /** 422 | * Helper to create a new Peer instance 423 | * @param opts Configuration options for the peer. 424 | * @returns {Promise} Resolves to the newly created Peer 425 | * @throws {Error} When unable to connect to signaling server. Likely networking issue. 426 | */ 427 | export async function createPeer(opts: PeerOptions): Promise { 428 | // TODO: add hook for refresh token 429 | const token = opts.token; 430 | const transport = new GrpcWebFetchTransport({ 431 | baseUrl: opts.baseUrl || BASE_URL, 432 | sendJson: false, 433 | format: "binary", 434 | jsonOptions: { 435 | emitDefaultValues: true, // treat zero values as values instead of undefined. 436 | enumAsInteger: true, 437 | ignoreUnknownFields: true, 438 | }, 439 | interceptors: [ 440 | { 441 | // adds auth header to unary requests 442 | interceptUnary(next, method, input, options: RpcOptions): UnaryCall { 443 | if (!options.meta) { 444 | options.meta = {}; 445 | } 446 | options.meta["Authorization"] = `Bearer ${token}`; 447 | return next(method, input, options); 448 | }, 449 | }, 450 | ], 451 | }); 452 | const client = new SignalingClient(transport); 453 | 454 | const resp = await retry( 455 | async () => await client.prepare({}), 456 | { 457 | baseDelay: 50, 458 | maxDelay: 1000, 459 | maxRetries: 5, 460 | isRecoverable: isRecoverable, 461 | }, 462 | ); 463 | if (resp === null) { 464 | throw new Error("createPeer aborted"); 465 | } 466 | const iceServers = [...(opts.iceServers || [])]; 467 | for (const s of resp.response.iceServers) { 468 | iceServers.push({ 469 | urls: s.urls, 470 | username: s.username, 471 | credential: s.credential, 472 | }); 473 | } 474 | const decoded = jwtDecode(token); 475 | const optsFull: PeerOptionsFull = { 476 | ...opts, 477 | "iceServers": iceServers, 478 | groupId: decoded.gid, 479 | peerId: decoded.pid, 480 | }; 481 | const peer = new Peer( 482 | new Logger("pulsebeam", undefined, PRETTY_LOG_SINK), 483 | client, 484 | optsFull, 485 | isRecoverable, 486 | ); 487 | return peer; 488 | } 489 | -------------------------------------------------------------------------------- /peer/src/session.ts: -------------------------------------------------------------------------------- 1 | import { 2 | AnalyticsMetrics, 3 | AnalyticsReport, 4 | ErrorEvent, 5 | type ICECandidate, 6 | IceCandidateEvent, 7 | MediaHandlingEvent, 8 | type PeerInfo, 9 | SdpKind, 10 | type Signal, 11 | SignalingEvent, 12 | } from "./signaling.ts"; 13 | import { Logger } from "./logger.ts"; 14 | import type { Stream } from "./transport.ts"; 15 | import * as analytics from "./analytics.ts"; 16 | 17 | const ICE_RESTART_MAX_COUNT = 1; 18 | const ICE_RESTART_DEBOUNCE_DELAY_MS = 5000; 19 | const INTERNAL_DATA_CHANNEL = "__internal"; 20 | 21 | function toIceCandidate(ice: ICECandidate): RTCIceCandidateInit { 22 | return { 23 | candidate: ice.candidate, 24 | sdpMid: ice.sdpMid, 25 | sdpMLineIndex: ice.sdpMLineIndex, 26 | usernameFragment: ice.password, 27 | }; 28 | } 29 | 30 | function toSDPType(kind: SdpKind): RTCSdpType { 31 | switch (kind) { 32 | case SdpKind.OFFER: 33 | return "offer"; 34 | case SdpKind.ANSWER: 35 | return "answer"; 36 | case SdpKind.PRANSWER: 37 | return "pranswer"; 38 | case SdpKind.ROLLBACK: 39 | return "rollback"; 40 | default: 41 | throw new Error(`unexpected kind: ${kind}`); 42 | } 43 | } 44 | 45 | function fromSDPType(t: RTCSdpType): SdpKind { 46 | switch (t) { 47 | case "offer": 48 | return SdpKind.OFFER; 49 | case "answer": 50 | return SdpKind.ANSWER; 51 | case "pranswer": 52 | return SdpKind.PRANSWER; 53 | case "rollback": 54 | return SdpKind.ROLLBACK; 55 | default: 56 | throw new Error(`unexpected sdp type: ${t}`); 57 | } 58 | } 59 | 60 | /** 61 | * The Session class is a wrapper around RTCPeerConnection designed to manage 62 | * WebRTC connections, signaling, and ICE candidates. It handles negotiation, 63 | * ICE restarts, signaling messages, and connection lifecycle events. 64 | */ 65 | export class Session { 66 | private pc: RTCPeerConnection; 67 | private makingOffer: boolean; 68 | private impolite: boolean; 69 | private pendingCandidates: RTCIceCandidateInit[]; 70 | private iceBatcher: IceCandidateBatcher; 71 | private readonly logger: Logger; 72 | private abort: AbortController; 73 | private generationCounter: number; 74 | private iceRestartCount: number; 75 | private lastIceRestart: number; 76 | private timers: number[]; 77 | private _closeReason?: string; 78 | private _connectionState: RTCPeerConnectionState; 79 | private internalDataChannel: RTCDataChannel; 80 | private _metrics: AnalyticsMetrics[]; 81 | 82 | /** 83 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/ondatachannel} 84 | */ 85 | public ondatachannel: RTCPeerConnection["ondatachannel"] = () => { }; 86 | 87 | /** 88 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/onconnectionstatechange} 89 | */ 90 | public onconnectionstatechange: RTCPeerConnection["onconnectionstatechange"] = 91 | () => { }; 92 | 93 | /** 94 | * Callback invoked when a new media track is added to the connection. 95 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/ontrack} 96 | */ 97 | public ontrack: RTCPeerConnection["ontrack"] = () => { }; 98 | 99 | /** 100 | * Adds a media track to the connection. 101 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/addTrack} 102 | * @returns {RTCRtpSender} the newly created track 103 | */ 104 | addTrack(track: MediaStreamTrack, ...streams: MediaStream[]): RTCRtpSender { 105 | if (track.kind === "audio") { 106 | this.recordEvent({ 107 | mediaHandlingEvent: MediaHandlingEvent.MEDIA_LOCAL_VIDEO_TRACK_ADDED, 108 | }); 109 | } else if (track.kind === "video") { 110 | this.recordEvent({ 111 | mediaHandlingEvent: MediaHandlingEvent.MEDIA_LOCAL_VIDEO_TRACK_ADDED, 112 | }); 113 | } 114 | return this.pc.addTrack(track, ...streams); 115 | } 116 | 117 | /** 118 | * The getSenders() method of the RTCPeerConnection interface returns an array of RTCRtpSender objects, 119 | * each of which represents the RTP sender responsible for transmitting one track's data. 120 | * A sender object provides methods and properties for examining and controlling the encoding and transmission of the track's data. 121 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/getSenders} 122 | * @returns {RTCRtpSender[]} 123 | */ 124 | getSenders(): RTCRtpSender[] { 125 | return this.pc.getSenders(); 126 | } 127 | 128 | /** 129 | * Removes a media track from the connection. 130 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/removeTrack} 131 | * @returns {void} 132 | */ 133 | removeTrack(sender: RTCRtpSender): void { 134 | if (sender.track?.kind === "audio") { 135 | this.recordEvent({ 136 | mediaHandlingEvent: MediaHandlingEvent.MEDIA_LOCAL_AUDIO_TRACK_REMOVED, 137 | }); 138 | } else if (sender.track?.kind === "video") { 139 | this.recordEvent({ 140 | mediaHandlingEvent: MediaHandlingEvent.MEDIA_LOCAL_VIDEO_TRACK_REMOVED, 141 | }); 142 | } 143 | return this.pc.removeTrack(sender); 144 | } 145 | 146 | /** 147 | * Creates a data channel (useful for sending arbitrary data) through the connection. 148 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createDataChannel} 149 | */ 150 | createDataChannel( 151 | ...args: Parameters 152 | ): RTCDataChannel { 153 | return this.pc.createDataChannel(...args); 154 | } 155 | 156 | getStats( 157 | ...args: Parameters 158 | ): Promise { 159 | return this.pc.getStats(...args); 160 | } 161 | 162 | /** 163 | * Returns the current connection state of the underlying RTCPeerConnection 164 | * See {@link https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/connectionState} 165 | * @returns {RTCPeerConnectionState} 166 | */ 167 | get connectionState(): RTCPeerConnectionState { 168 | return this.pc.connectionState; 169 | } 170 | 171 | /** 172 | * If reason is available, returns the reason for the session being closed. 173 | * @returns {string | undefined} 174 | */ 175 | get closeReason(): string | undefined { 176 | return this._closeReason; 177 | } 178 | 179 | /** 180 | * Retrieves the identifier of the other peer. 181 | * @returns {string} 182 | */ 183 | get other(): PeerInfo { 184 | return { 185 | groupId: this.stream.other.groupId, 186 | peerId: this.stream.other.peerId, 187 | connId: this.stream.other.connId, 188 | }; 189 | } 190 | 191 | /** 192 | * Closes the session, aborts pending tasks, and cleans up resources. 193 | * Publishes events and logs. 194 | * @param {string} [reason] - (optional) Your reason for closing the session. 195 | * @returns {void} 196 | * @example mysession.close("Normal closure"); 197 | */ 198 | close(reason?: string): void { 199 | if (this.abort.signal.aborted) return; 200 | this.abort.abort(reason); 201 | for (const timer of this.timers) { 202 | clearTimeout(timer); 203 | } 204 | this.timers = []; 205 | this.iceBatcher.close(); 206 | this.stream.close(); 207 | this._closeReason = reason; 208 | this.pc.close(); 209 | 210 | // RTCPeerConnection will not emit closed connection. This is a polyfill to get around it. 211 | // https://stackoverflow.com/questions/66297347/why-does-calling-rtcpeerconnection-close-not-send-closed-event 212 | const closeEvent = new Event("connectionstatechange"); 213 | this.setConnectionState("closed", closeEvent); 214 | 215 | this.logger.debug("session closed", { 216 | connectionState: this.connectionState, 217 | reason, 218 | }); 219 | } 220 | 221 | /** 222 | * Creates a Session with the provided stream and 223 | * configs. Sets up event handlers, signaling, and ICE candidate 224 | * management. 225 | * See {@link Session} For class responsibilities 226 | * @param stream Represents the transport stream for signaling messages. 227 | * @param config Configuration object for the RTCPeerConnection. 228 | */ 229 | constructor( 230 | private readonly stream: Stream, 231 | config: RTCConfiguration, 232 | ) { 233 | this.pc = new RTCPeerConnection(config); 234 | 235 | this.makingOffer = false; 236 | this.pendingCandidates = []; 237 | // Higher is impolite. [0-15] is reserved. One of the reserved value can be used 238 | // for implementing fixed "polite" role for lite ICE. 239 | if (this.stream.info.connId === this.stream.other.connId) { 240 | this.impolite = this.stream.info.peerId > this.stream.other.peerId; 241 | } else { 242 | this.impolite = this.stream.info.connId > this.stream.other.connId; 243 | } 244 | this.abort = new AbortController(); 245 | this.logger = stream.logger.sub("session", { 246 | role: this.impolite ? "impolite" : "polite", 247 | }); 248 | this.generationCounter = 0; 249 | this.iceRestartCount = 0; 250 | this.lastIceRestart = 0; 251 | this.timers = []; 252 | this._connectionState = "new"; 253 | this._metrics = []; 254 | this.iceBatcher = new IceCandidateBatcher( 255 | this.logger, 256 | 100, 257 | (c) => this.sendLocalIceCandidates(c), 258 | ); 259 | stream.onsignal = (msg) => this.handleSignal(msg); 260 | stream.onclosed = (reason) => this.close(reason); 261 | 262 | this.pc.oniceconnectionstatechange = async () => { 263 | const stats = await this.pc.getStats(); 264 | const pair: unknown[] = []; 265 | const local: unknown[] = []; 266 | const remote: unknown[] = []; 267 | // https://developer.mozilla.org/en-US/docs/Web/API/RTCStatsReport#the_statistic_types 268 | stats.forEach((report: RTCStats) => { 269 | if (report.type === "candidate-pair") { 270 | pair.push(report); 271 | } else if (report.type === "local-candidate") { 272 | local.push(report); 273 | } else if (report.type === "remote-candidate") { 274 | remote.push(report); 275 | } 276 | }); 277 | 278 | this.logger.debug("iceconnectionstate changed", { 279 | "connectionstate": this.pc.connectionState, 280 | "iceconnectionstate": this.pc.iceConnectionState, 281 | local, 282 | remote, 283 | pair, 284 | pending: this.pendingCandidates, 285 | }); 286 | }; 287 | 288 | this.pc.onsignalingstatechange = () => { 289 | this.checkPendingCandidates(); 290 | }; 291 | 292 | let start = performance.now(); 293 | this.pc.onconnectionstatechange = (ev) => { 294 | this.logger.debug("connectionstate changed", { 295 | "connectionstate": this.pc.connectionState, 296 | "iceconnectionstate": this.pc.iceConnectionState, 297 | }); 298 | this.setConnectionState(this.pc.connectionState, ev); 299 | switch (this.pc.connectionState) { 300 | case "new": 301 | break; 302 | case "connecting": 303 | start = performance.now(); 304 | break; 305 | case "connected": { 306 | const elapsed = performance.now() - start; 307 | this.logger.debug(`it took ${elapsed}ms to connect`); 308 | this.recordEvent({ 309 | iceCandidateEvent: IceCandidateEvent.ICE_CANDIDATE_PAIRING_SUCCESS, 310 | }); 311 | this.iceRestartCount = 0; 312 | break; 313 | } 314 | case "disconnected": 315 | break; 316 | case "failed": 317 | this.recordEvent({ 318 | errorEvent: ErrorEvent.ERROR_ICE_CONNECTION_FAILED, 319 | }); 320 | this.triggerIceRestart(); 321 | break; 322 | case "closed": 323 | break; 324 | } 325 | }; 326 | this.pc.onnegotiationneeded = this.onnegotiationneeded.bind(this); 327 | this.pc.onicecandidate = ({ candidate }) => { 328 | // Record specific candidate types found 329 | if (candidate) { 330 | // Use the specific local candidate found events based on type 331 | switch (candidate.type) { 332 | case "host": 333 | this.recordEvent({ 334 | iceCandidateEvent: 335 | IceCandidateEvent.ICE_CANDIDATE_LOCAL_HOST_FOUND, 336 | }); 337 | break; 338 | case "srflx": 339 | this.recordEvent({ 340 | iceCandidateEvent: 341 | IceCandidateEvent.ICE_CANDIDATE_LOCAL_SRFLX_FOUND, 342 | }); 343 | break; 344 | case "prflx": 345 | // Note: Local prflx is less common, browser might report as host/srflx after STUN checks 346 | this.recordEvent({ 347 | iceCandidateEvent: 348 | IceCandidateEvent.ICE_CANDIDATE_LOCAL_PRFLX_FOUND, 349 | }); 350 | break; 351 | case "relay": 352 | this.recordEvent({ 353 | iceCandidateEvent: 354 | IceCandidateEvent.ICE_CANDIDATE_LOCAL_RELAY_FOUND, 355 | }); // Assuming REFLEXIVE meant RELAY based on common usage 356 | break; 357 | default: 358 | this.logger.warn("Unknown local ICE candidate type", { 359 | type: candidate.type, 360 | }); 361 | break; 362 | } 363 | } else { 364 | // ICE Gathering Complete 365 | this.recordEvent({ 366 | iceCandidateEvent: 367 | IceCandidateEvent.ICE_CANDIDATE_GATHERING_COMPLETED, 368 | }); 369 | } 370 | this.iceBatcher.addCandidate(candidate); 371 | }; 372 | 373 | this.pc.ondatachannel = (ev) => { 374 | if (ev.channel.label === INTERNAL_DATA_CHANNEL) { 375 | return; 376 | } 377 | 378 | if (this.ondatachannel) { 379 | // @ts-ignore: proxy to RTCPeerConnection 380 | this.ondatachannel(ev); 381 | } 382 | }; 383 | 384 | this.pc.ontrack = (ev) => { 385 | if (ev.track.kind === "audio") { 386 | this.recordEvent({ 387 | mediaHandlingEvent: MediaHandlingEvent.MEDIA_REMOTE_AUDIO_TRACK_ADDED, 388 | }); 389 | } else if (ev.track.kind === "video") { 390 | this.recordEvent({ 391 | mediaHandlingEvent: MediaHandlingEvent.MEDIA_REMOTE_VIDEO_TRACK_ADDED, 392 | }); 393 | } 394 | 395 | if (this.ontrack) { 396 | // @ts-ignore: proxy to RTCPeerConnection 397 | this.ontrack(ev); 398 | } 399 | }; 400 | 401 | this.internalDataChannel = this.pc.createDataChannel(INTERNAL_DATA_CHANNEL); 402 | // NOTE: reserve internal data channel usage 403 | this.internalDataChannel; 404 | } 405 | 406 | private recordEvent(metric: Omit) { 407 | const now = analytics.now(); 408 | this._metrics.push({ 409 | ...metric, 410 | timestampUs: now, 411 | }); 412 | } 413 | 414 | public async collectMetrics(): Promise { 415 | const rawStats = await this.getStats(); 416 | const quality = analytics.calculateQualityScore(rawStats); 417 | if (!!quality) { 418 | this.recordEvent({ 419 | qualityScore: quality.qualityScore, 420 | rttUs: quality.rttUs, 421 | }); 422 | } 423 | 424 | const buffered = this._metrics; 425 | this._metrics = []; 426 | return { 427 | tags: { 428 | src: this.stream.info, 429 | dst: this.other, 430 | }, 431 | metrics: buffered, 432 | }; 433 | } 434 | 435 | private async onnegotiationneeded() { 436 | try { 437 | this.recordEvent({ 438 | signalingEvent: SignalingEvent.SIGNALING_NEGOTIATION_NEEDED, 439 | }); 440 | this.makingOffer = true; 441 | this.logger.debug("creating an offer"); 442 | 443 | await this.setLocalDescription(); 444 | if (!this.pc.localDescription) { 445 | throw new Error("expect localDescription to be not empty"); 446 | } 447 | 448 | this.sendSignal({ 449 | data: { 450 | oneofKind: "sdp", 451 | sdp: { 452 | kind: fromSDPType(this.pc.localDescription.type), 453 | sdp: this.pc.localDescription.sdp, 454 | }, 455 | }, 456 | }); 457 | } catch (err) { 458 | if (err instanceof Error) { 459 | this.logger.error("failed in negotiating", { err }); 460 | } 461 | } finally { 462 | this.makingOffer = false; 463 | } 464 | } 465 | 466 | private sendLocalIceCandidates(candidates: RTCIceCandidate[]) { 467 | const batch: ICECandidate[] = []; 468 | for (const candidate of candidates) { 469 | const ice: ICECandidate = { 470 | candidate: "", 471 | sdpMLineIndex: 0, 472 | sdpMid: "", 473 | }; 474 | 475 | ice.candidate = candidate.candidate; 476 | ice.sdpMLineIndex = candidate.sdpMLineIndex ?? undefined; 477 | ice.sdpMid = candidate.sdpMid ?? undefined; 478 | ice.username = candidate.usernameFragment ?? undefined; 479 | batch.push(ice); 480 | } 481 | 482 | this.sendSignal({ 483 | data: { 484 | oneofKind: "iceCandidateBatch", 485 | iceCandidateBatch: { 486 | candidates: batch, 487 | }, 488 | }, 489 | }); 490 | } 491 | 492 | /** internal @private */ 493 | private setConnectionState(s: RTCPeerConnectionState, ev: Event): void { 494 | if (s === this._connectionState) return; 495 | 496 | if (this.onconnectionstatechange) { 497 | // @ts-ignore: proxy to RTCPeerConnection 498 | this.onconnectionstatechange(ev); 499 | } 500 | } 501 | 502 | private async setLocalDescription() { 503 | const transceivers = this.pc.getTransceivers(); 504 | for (const transceiver of transceivers) { 505 | if (transceiver.receiver.track.kind !== "video") { 506 | continue; 507 | } 508 | 509 | // https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpTransceiver/setCodecPreferences 510 | const preferredOrder = [ 511 | "video/AV1", 512 | "video/VP9", 513 | "video/VP8", 514 | "video/H264", 515 | ]; 516 | const codecs = RTCRtpReceiver.getCapabilities("video")?.codecs || []; 517 | const preferences = codecs.sort((a, b) => { 518 | const indexA = preferredOrder.indexOf(a.mimeType); 519 | const indexB = preferredOrder.indexOf(b.mimeType); 520 | const orderA = indexA >= 0 ? indexA : Number.MAX_VALUE; 521 | const orderB = indexB >= 0 ? indexB : Number.MAX_VALUE; 522 | return orderA - orderB; 523 | }); 524 | transceiver.setCodecPreferences(preferences); 525 | } 526 | 527 | for (const sender of this.pc.getSenders()) { 528 | if (sender.track?.kind !== "video") { 529 | continue; 530 | } 531 | 532 | // https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpSender/setParameters 533 | const parameters = sender.getParameters(); 534 | if (!parameters.encodings || parameters.encodings.length === 0) { 535 | parameters.encodings = [{}]; // Initialize if empty 536 | } 537 | 538 | parameters.encodings[0].maxBitrate = 400 * 1000; 539 | try { 540 | await sender.setParameters(parameters); 541 | } catch (e) { 542 | this.logger.warn("failed to change max bitrate", { error: e }); 543 | } 544 | } 545 | 546 | try { 547 | await this.pc.setLocalDescription(); 548 | } catch (e) { 549 | this.recordEvent({ 550 | errorEvent: ErrorEvent.ERROR_SDP_NEGOTIATION_FAILED, 551 | }); 552 | throw e; 553 | } 554 | } 555 | 556 | private triggerIceRestart = () => { 557 | // // the impolite offer will trigger the polite peer's to also restart Ice 558 | // if (!this.impolite) return; 559 | // 560 | const elapsed = performance.now() - this.lastIceRestart; 561 | if (elapsed < ICE_RESTART_DEBOUNCE_DELAY_MS) { 562 | // schedule ice restart after some delay; 563 | const delay = ICE_RESTART_DEBOUNCE_DELAY_MS - elapsed; 564 | const timerId = window.setTimeout(() => { 565 | this.triggerIceRestart(); 566 | this.timers = this.timers.filter((v) => v === timerId); 567 | }, delay); 568 | return; 569 | } 570 | 571 | if (this.pc.connectionState === "connected") return; 572 | if (this.iceRestartCount >= ICE_RESTART_MAX_COUNT) { 573 | this.close("detected sustained network failure"); 574 | return; 575 | } 576 | this.logger.debug("triggered ICE restart"); 577 | this.pc.restartIce(); 578 | this.recordEvent({ 579 | signalingEvent: SignalingEvent.SIGNALING_ICE_RESTART_TRIGGERED, 580 | }); 581 | 582 | this.generationCounter++; 583 | this.iceRestartCount++; 584 | this.lastIceRestart = performance.now(); 585 | }; 586 | 587 | private sendSignal = (signal: Omit) => { 588 | if (signal.data.oneofKind === "sdp") { 589 | const sdpKind = signal.data.sdp.kind; 590 | if (sdpKind === SdpKind.OFFER) { 591 | this.recordEvent({ 592 | signalingEvent: SignalingEvent.SIGNALING_OFFER_SENT, 593 | }); 594 | } else if (sdpKind === SdpKind.ANSWER) { 595 | this.recordEvent({ 596 | signalingEvent: SignalingEvent.SIGNALING_ANSWER_SENT, 597 | }); 598 | } 599 | } 600 | 601 | this.stream.send({ 602 | payloadType: { 603 | oneofKind: "signal", 604 | signal: { ...signal, generationCounter: this.generationCounter }, 605 | }, 606 | }, true); 607 | }; 608 | 609 | private handleSignal = async (signal: Signal) => { 610 | if (signal.generationCounter < this.generationCounter) { 611 | this.logger.warn("detected staled generationCounter signals, ignoring"); 612 | return; 613 | } 614 | 615 | this.addCandidates(signal); 616 | const msg = signal.data; 617 | if (signal.generationCounter > this.generationCounter) { 618 | // Sync generationCounter so this peer can reset its state machine 619 | // to start accepting new offers 620 | this.logger.debug("detected new generationCounter", { 621 | otherGenerationCounter: signal.generationCounter, 622 | generationCounter: this.generationCounter, 623 | msg, 624 | }); 625 | 626 | if (msg.oneofKind === "iceCandidate") { 627 | this.logger.warn( 628 | "expecting an offer but got ice candidates during an ICE restart, adding to pending.", 629 | { msg }, 630 | ); 631 | return; 632 | } 633 | 634 | this.generationCounter = signal.generationCounter; 635 | } 636 | 637 | if (msg.oneofKind != "sdp") { 638 | return; 639 | } 640 | 641 | const sdp = msg.sdp; 642 | this.logger.debug("received a SDP signal", { sdpKind: sdp.kind }); 643 | if (sdp.kind === SdpKind.OFFER) { 644 | this.recordEvent({ 645 | signalingEvent: SignalingEvent.SIGNALING_OFFER_RECEIVED, 646 | }); 647 | } else if (sdp.kind === SdpKind.ANSWER) { 648 | this.recordEvent({ 649 | signalingEvent: SignalingEvent.SIGNALING_ANSWER_RECEIVED, 650 | }); 651 | } 652 | 653 | const offerCollision = sdp.kind === SdpKind.OFFER && 654 | (this.makingOffer || this.pc.signalingState !== "stable"); 655 | 656 | const ignoreOffer = this.impolite && offerCollision; 657 | if (ignoreOffer) { 658 | this.logger.debug("ignored offer"); 659 | return; 660 | } 661 | 662 | this.logger.debug("creating an answer"); 663 | await this.pc.setRemoteDescription({ 664 | type: toSDPType(sdp.kind), 665 | sdp: sdp.sdp, 666 | }); 667 | if (sdp.kind === SdpKind.OFFER) { 668 | await this.setLocalDescription(); 669 | if (!this.pc.localDescription) { 670 | this.logger.error("unexpected null local description"); 671 | return; 672 | } 673 | 674 | // when a signal is retried many times and still failing. The failing heartbeat will kick in and close. 675 | this.sendSignal({ 676 | data: { 677 | oneofKind: "sdp", 678 | sdp: { 679 | kind: fromSDPType(this.pc.localDescription.type), 680 | sdp: this.pc.localDescription.sdp, 681 | }, 682 | }, 683 | }); 684 | } 685 | this.checkPendingCandidates(); 686 | return; 687 | }; 688 | 689 | private addCandidates(msg: Signal) { 690 | const candidates = []; 691 | if (msg.data.oneofKind === "iceCandidate") { 692 | candidates.push(msg.data.iceCandidate); 693 | } else if (msg.data.oneofKind === "iceCandidateBatch") { 694 | candidates.push(...msg.data.iceCandidateBatch.candidates); 695 | } else { 696 | return; 697 | } 698 | 699 | this.pendingCandidates.push(...candidates.map((v) => toIceCandidate(v))); 700 | this.checkPendingCandidates(); 701 | } 702 | 703 | private checkPendingCandidates = () => { 704 | const safeStates: RTCSignalingState[] = [ 705 | "stable", 706 | "have-local-offer", 707 | "have-remote-offer", 708 | ]; 709 | if ( 710 | !safeStates.includes(this.pc.signalingState) || !this.pc.remoteDescription 711 | ) { 712 | this.logger.debug("wait for adding pending candidates", { 713 | signalingState: this.pc.signalingState, 714 | iceConnectionState: this.pc.iceConnectionState, 715 | connectionState: this.pc.connectionState, 716 | remoteDescription: this.pc.remoteDescription, 717 | pendingCandidates: this.pendingCandidates.length, 718 | }); 719 | return; 720 | } 721 | 722 | for (const candidate of this.pendingCandidates) { 723 | if (!candidate.candidate || candidate.candidate === "") { 724 | continue; 725 | } 726 | 727 | // intentionally not awaiting, otherwise we might be in a different state than we originally 728 | // checked. 729 | this.pc.addIceCandidate(candidate).catch((e) => { 730 | this.logger.warn("failed to add candidate, skipping.", { 731 | candidate, 732 | e, 733 | }); 734 | }); 735 | this.logger.debug(`added ice: ${candidate.candidate}`); 736 | } 737 | this.pendingCandidates = []; 738 | }; 739 | } 740 | 741 | class IceCandidateBatcher { 742 | private candidates: RTCIceCandidate[] = []; 743 | private timeoutId: NodeJS.Timeout | null = null; 744 | private delayMs: number; 745 | private logger: Logger; 746 | private onIceCandidates: (candidates: RTCIceCandidate[]) => void; 747 | 748 | constructor( 749 | logger: Logger, 750 | delayMs: number, 751 | onIceCandidates: (candidates: RTCIceCandidate[]) => void, 752 | ) { 753 | this.logger = logger.sub("icebatcher"); 754 | this.delayMs = delayMs; 755 | this.onIceCandidates = onIceCandidates; 756 | } 757 | 758 | public addCandidate = (candidate: RTCIceCandidate | null): void => { 759 | if (!candidate || candidate.candidate === "") { 760 | this.logger.debug( 761 | "ice gathering is finished, force flush local candidates", 762 | ); 763 | this.flushCandidates(); 764 | return; 765 | } 766 | 767 | this.logger.debug("onicecandidate", { candidate }); 768 | this.candidates.push(candidate); 769 | if (!this.timeoutId) { 770 | // First candidate received, start the timer 771 | this.timeoutId = setTimeout(this.flushCandidates, this.delayMs); 772 | } else { 773 | // Subsequent candidate received, reset the timer 774 | clearTimeout(this.timeoutId); 775 | this.timeoutId = setTimeout(this.flushCandidates, this.delayMs); 776 | } 777 | }; 778 | 779 | private flushCandidates = (): void => { 780 | if (this.candidates.length > 0) { 781 | this.onIceCandidates(this.candidates); 782 | this.candidates = []; 783 | } 784 | this.timeoutId = null; 785 | }; 786 | 787 | public flush = (): void => { 788 | if (this.timeoutId) { 789 | clearTimeout(this.timeoutId); 790 | } 791 | this.flushCandidates(); 792 | }; 793 | 794 | public close = (): void => { 795 | if (this.timeoutId) { 796 | clearTimeout(this.timeoutId); 797 | } 798 | }; 799 | } 800 | -------------------------------------------------------------------------------- /peer/src/signaling.client.ts: -------------------------------------------------------------------------------- 1 | // @generated by protobuf-ts 2.9.4 with parameter client_generic 2 | // @generated from protobuf file "signaling.proto" (package "pulsebeam.v1", syntax proto3) 3 | // tslint:disable 4 | import type { RpcTransport } from "@protobuf-ts/runtime-rpc"; 5 | import type { ServiceInfo } from "@protobuf-ts/runtime-rpc"; 6 | import { Signaling } from "./signaling.ts"; 7 | import type { AnalyticsReportResp } from "./signaling.ts"; 8 | import type { AnalyticsReportReq } from "./signaling.ts"; 9 | import type { RecvResp } from "./signaling.ts"; 10 | import type { RecvReq } from "./signaling.ts"; 11 | import type { ServerStreamingCall } from "@protobuf-ts/runtime-rpc"; 12 | import type { SendResp } from "./signaling.ts"; 13 | import type { SendReq } from "./signaling.ts"; 14 | import { stackIntercept } from "@protobuf-ts/runtime-rpc"; 15 | import type { PrepareResp } from "./signaling.ts"; 16 | import type { PrepareReq } from "./signaling.ts"; 17 | import type { UnaryCall } from "@protobuf-ts/runtime-rpc"; 18 | import type { RpcOptions } from "@protobuf-ts/runtime-rpc"; 19 | /** 20 | * @generated from protobuf service pulsebeam.v1.Signaling 21 | */ 22 | export interface ISignalingClient { 23 | /** 24 | * @generated from protobuf rpc: Prepare(pulsebeam.v1.PrepareReq) returns (pulsebeam.v1.PrepareResp); 25 | */ 26 | prepare(input: PrepareReq, options?: RpcOptions): UnaryCall; 27 | /** 28 | * @generated from protobuf rpc: Send(pulsebeam.v1.SendReq) returns (pulsebeam.v1.SendResp); 29 | */ 30 | send(input: SendReq, options?: RpcOptions): UnaryCall; 31 | /** 32 | * @generated from protobuf rpc: Recv(pulsebeam.v1.RecvReq) returns (stream pulsebeam.v1.RecvResp); 33 | */ 34 | recv(input: RecvReq, options?: RpcOptions): ServerStreamingCall; 35 | /** 36 | * @generated from protobuf rpc: AnalyticsReport(pulsebeam.v1.AnalyticsReportReq) returns (pulsebeam.v1.AnalyticsReportResp); 37 | */ 38 | analyticsReport(input: AnalyticsReportReq, options?: RpcOptions): UnaryCall; 39 | } 40 | /** 41 | * @generated from protobuf service pulsebeam.v1.Signaling 42 | */ 43 | export class SignalingClient implements ISignalingClient, ServiceInfo { 44 | typeName = Signaling.typeName; 45 | methods = Signaling.methods; 46 | options = Signaling.options; 47 | constructor(private readonly _transport: RpcTransport) { 48 | } 49 | /** 50 | * @generated from protobuf rpc: Prepare(pulsebeam.v1.PrepareReq) returns (pulsebeam.v1.PrepareResp); 51 | */ 52 | prepare(input: PrepareReq, options?: RpcOptions): UnaryCall { 53 | const method = this.methods[0], opt = this._transport.mergeOptions(options); 54 | return stackIntercept("unary", this._transport, method, opt, input); 55 | } 56 | /** 57 | * @generated from protobuf rpc: Send(pulsebeam.v1.SendReq) returns (pulsebeam.v1.SendResp); 58 | */ 59 | send(input: SendReq, options?: RpcOptions): UnaryCall { 60 | const method = this.methods[1], opt = this._transport.mergeOptions(options); 61 | return stackIntercept("unary", this._transport, method, opt, input); 62 | } 63 | /** 64 | * @generated from protobuf rpc: Recv(pulsebeam.v1.RecvReq) returns (stream pulsebeam.v1.RecvResp); 65 | */ 66 | recv(input: RecvReq, options?: RpcOptions): ServerStreamingCall { 67 | const method = this.methods[2], opt = this._transport.mergeOptions(options); 68 | return stackIntercept("serverStreaming", this._transport, method, opt, input); 69 | } 70 | /** 71 | * @generated from protobuf rpc: AnalyticsReport(pulsebeam.v1.AnalyticsReportReq) returns (pulsebeam.v1.AnalyticsReportResp); 72 | */ 73 | analyticsReport(input: AnalyticsReportReq, options?: RpcOptions): UnaryCall { 74 | const method = this.methods[3], opt = this._transport.mergeOptions(options); 75 | return stackIntercept("unary", this._transport, method, opt, input); 76 | } 77 | } 78 | -------------------------------------------------------------------------------- /peer/src/store.ts: -------------------------------------------------------------------------------- 1 | import { 2 | atom, 3 | computed, 4 | map, 5 | PreinitializedMapStore, 6 | PreinitializedWritableAtom, 7 | ReadableAtom, 8 | } from "nanostores"; 9 | import { Peer, PeerInfo, PeerState } from "./peer.ts"; 10 | 11 | export type Value = string | number | undefined; 12 | export type Key = string; 13 | 14 | interface CRDTEntry { 15 | value: Value; 16 | version: number; 17 | replicaId: string; 18 | } 19 | 20 | export type KVStore = Record; 21 | type CRDTKV = Record; 22 | 23 | interface CRDTRemoteUpdate { 24 | key: Key; 25 | entry: CRDTEntry; 26 | } 27 | 28 | export interface RemotePeer { 29 | info: PeerInfo; 30 | streams: MediaStream[]; 31 | state: RTCPeerConnectionState; 32 | } 33 | 34 | export class PeerStore { 35 | public static readonly KV_NAMESPACE = "__crdt_kv"; 36 | public readonly $kv: PreinitializedMapStore & object; 37 | public readonly $streams: 38 | & PreinitializedMapStore> 39 | & object; 40 | 41 | public readonly $remotePeers: ReadableAtom>; 42 | public readonly $state: ReadableAtom; 43 | 44 | private readonly $_remotePeers: 45 | & PreinitializedMapStore> 46 | & object; 47 | private readonly $_state: PreinitializedWritableAtom; 48 | private readonly crdtStore: CRDTKV; 49 | private replicaId: string; 50 | private sendChannels: Record; 51 | 52 | constructor(public readonly peer: Peer) { 53 | this.crdtStore = {}; 54 | this.$kv = map({}); 55 | this.$streams = map>({}); 56 | this.$_remotePeers = map>({}); 57 | this.$remotePeers = computed(this.$_remotePeers, (v) => v); 58 | this.$_state = atom("new"); 59 | this.$state = computed(this.$_state, (v) => v); 60 | this.sendChannels = {}; 61 | this.replicaId = peer.peerId; 62 | 63 | peer.onstatechange = () => { 64 | this.$_state.set(peer.state); 65 | }; 66 | 67 | peer.onsession = (sess) => { 68 | const id = 69 | `${sess.other.groupId}:${sess.other.peerId}:${sess.other.connId}`; 70 | // https://stackoverflow.com/questions/54292824/webrtc-channel-reliability 71 | this.sendChannels[id] = sess.createDataChannel(PeerStore.KV_NAMESPACE, { 72 | ordered: true, 73 | }); 74 | 75 | sess.ondatachannel = (e) => { 76 | console.log("debug:ondatachannel", e.channel.label); 77 | if (e.channel.label !== PeerStore.KV_NAMESPACE) { 78 | return; 79 | } 80 | 81 | e.channel.onmessage = (ev) => { 82 | // TODO: validate schema? 83 | const update = JSON.parse(ev.data) as CRDTRemoteUpdate; 84 | console.log("debug:onmessage", { update }); 85 | this.receiveUpdate(update.key, update.entry); 86 | }; 87 | 88 | // TODO: limit full sync up to 3 peers? 89 | e.channel.onopen = (_ev) => { 90 | console.log("debug:sync", { crdt: this.crdtStore }); 91 | for (const [key, entry] of Object.entries(this.crdtStore)) { 92 | console.log("debug:notifying", { key, entry }); 93 | this.notifyPeer(this.sendChannels[id], { 94 | key, 95 | entry, 96 | }); 97 | } 98 | }; 99 | }; 100 | 101 | sess.ontrack = (ev) => { 102 | // TODO: find existing and update 103 | const remotePeer = this.$_remotePeers.get()[id]; 104 | for (const stream of ev.streams) { 105 | const result = remotePeer.streams.findIndex((v) => 106 | v.id === stream.id 107 | ); 108 | 109 | stream.onremovetrack = (ev) => { 110 | console.log("debug:onremovetrack", ev.track); 111 | for (const stream of remotePeer.streams) { 112 | stream.removeTrack(ev.track); 113 | } 114 | remotePeer.streams = remotePeer.streams.filter((s) => s.active); 115 | this.$_remotePeers.setKey(id, { 116 | ...remotePeer, 117 | }); 118 | }; 119 | 120 | if (!stream.active) { 121 | if (result !== -1) { 122 | remotePeer.streams.splice(result, 1); 123 | } 124 | continue; 125 | } 126 | 127 | if (result === -1) { 128 | remotePeer.streams.push(stream); 129 | } else { 130 | remotePeer.streams[result] = stream; 131 | } 132 | } 133 | this.$_remotePeers.setKey(id, { 134 | ...remotePeer, 135 | }); 136 | console.log("debug:ontrack", { id, streams: remotePeer.streams }); 137 | }; 138 | 139 | sess.onconnectionstatechange = (_ev) => { 140 | if (sess.connectionState === "closed") { 141 | const current = this.$_remotePeers.get(); 142 | delete current[id]; 143 | delete this.sendChannels[id]; 144 | console.log(`connection failed, removed ${id}`); 145 | this.$_remotePeers.set({ ...current }); 146 | return; 147 | } 148 | 149 | const remotePeer = this.$_remotePeers.get()[id]; 150 | this.$_remotePeers.setKey(id, { 151 | ...remotePeer, 152 | state: sess.connectionState, 153 | }); 154 | }; 155 | 156 | const localStreams = Object.entries(this.$streams.get()); 157 | for (const [_id, stream] of localStreams) { 158 | if (!stream) continue; 159 | 160 | for (const track of stream.getTracks()) { 161 | sess.addTrack(track, stream); 162 | } 163 | console.log("debug:onsession", { _id, stream }); 164 | } 165 | 166 | this.$_remotePeers.setKey(id, { 167 | info: sess.other, 168 | streams: [], 169 | state: sess.connectionState, 170 | }); 171 | }; 172 | 173 | this.$kv.listen((newKV, _oldKV, changedKey) => { 174 | const newVal = newKV[changedKey]; 175 | this.set(changedKey, newVal); 176 | }); 177 | 178 | this.$streams.listen((newStreams, _oldStreams, _changedKey) => { 179 | console.log("debug:sync_streams", { newStreams }); 180 | for (const sess of this.peer.sessions) { 181 | const senders = sess.getSenders(); 182 | const currentSenders: Record = {}; 183 | const toRemove: Record = {}; 184 | 185 | for (const sender of senders) { 186 | // some senders are reserved for replying. Leave these senders as they 187 | // may be reused. 188 | if (!sender.track) continue; 189 | 190 | const toRemoveSenders = currentSenders[sender.track.id] || []; 191 | currentSenders[sender.track.id] = [...toRemoveSenders, sender]; 192 | toRemove[sender.track.id] = true; 193 | } 194 | 195 | for (const stream of Object.values(newStreams)) { 196 | if (!stream) continue; 197 | 198 | for (const track of stream.getTracks()) { 199 | if (track.id in currentSenders) { 200 | toRemove[track.id] = false; 201 | continue; 202 | } 203 | 204 | sess.addTrack(track, stream); 205 | } 206 | } 207 | 208 | for (const [trackId, remove] of Object.entries(toRemove)) { 209 | if (!remove) continue; 210 | const senders = currentSenders[trackId]; 211 | for (const sender of senders) { 212 | sender.track?.stop(); 213 | sess.removeTrack(sender); 214 | console.log("debug:removeTrack", { sender }); 215 | } 216 | } 217 | } 218 | }); 219 | this.peer.start(); 220 | } 221 | 222 | close() { 223 | this.peer.close(); 224 | } 225 | 226 | mute(disabled: boolean) { 227 | const streams = Object.values(this.$streams.get()); 228 | 229 | for (const stream of streams) { 230 | if (!stream) continue; 231 | for (const track of stream.getAudioTracks()) { 232 | track.enabled = !disabled; 233 | } 234 | } 235 | } 236 | 237 | private set(key: Key, value: Value) { 238 | const current = this.crdtStore[key]; 239 | if (!!current && current.value === value) { 240 | // TODO: use a better loopback detection 241 | return; 242 | } 243 | 244 | const entry = current 245 | ? { version: current.version + 1, replicaId: this.replicaId, value } 246 | : { version: 0, replicaId: this.replicaId, value }; 247 | this.notifyPeers(key, entry); 248 | } 249 | 250 | private notifyPeer(ch: RTCDataChannel, update: CRDTRemoteUpdate) { 251 | ch.send(JSON.stringify(update)); 252 | } 253 | 254 | private notifyPeers(key: Key, entry: CRDTEntry) { 255 | const update: CRDTRemoteUpdate = { 256 | key, 257 | entry, 258 | }; 259 | 260 | for (const ch of Object.values(this.sendChannels)) { 261 | this.notifyPeer(ch, update); 262 | } 263 | } 264 | 265 | private receiveUpdate(key: Key, remoteEntry: CRDTEntry): void { 266 | const currentEntry = this.crdtStore[key]; 267 | console.log("debug:received_update", { key, remoteEntry, currentEntry }); 268 | 269 | if ( 270 | !currentEntry 271 | ) { 272 | this.crdtStore[key] = remoteEntry; 273 | this.$kv.setKey(key, remoteEntry.value); 274 | console.log( 275 | "debug:received_update accepted (resolution=empty)", 276 | remoteEntry, 277 | ); 278 | } else if (remoteEntry.version > currentEntry.version) { 279 | this.crdtStore[key] = remoteEntry; 280 | this.$kv.setKey(key, remoteEntry.value); 281 | console.log( 282 | "debug:received_update accepted (resolution=older)", 283 | remoteEntry, 284 | ); 285 | } else if ( 286 | remoteEntry.version === currentEntry.version && 287 | remoteEntry.replicaId > this.replicaId 288 | ) { 289 | this.crdtStore[key] = remoteEntry; 290 | this.$kv.setKey(key, remoteEntry.value); 291 | console.log( 292 | "debug:received_update accepted (resolution=replicaId)", 293 | remoteEntry, 294 | ); 295 | } else { 296 | console.log("debug:received_update ignored remote update", { 297 | remoteEntry, 298 | currentEntry, 299 | }); 300 | return; 301 | } 302 | } 303 | } 304 | -------------------------------------------------------------------------------- /peer/src/transport.ts: -------------------------------------------------------------------------------- 1 | import type { 2 | AnalyticsReportReq, 3 | Message, 4 | MessageHeader, 5 | MessagePayload, 6 | PeerInfo, 7 | Signal, 8 | } from "./signaling.ts"; 9 | import { ISignalingClient } from "./signaling.client.ts"; 10 | import type { Logger } from "./logger.ts"; 11 | import { asleep, joinSignals, retry, RetryOptions } from "./util.ts"; 12 | import { RpcOptions } from "@protobuf-ts/runtime-rpc"; 13 | 14 | const POLL_TIMEOUT_MS = 900000; 15 | const POLL_RETRY_BASE_DELAY_MS = 250; 16 | const POLL_RETRY_MAX_DELAY_MS = 1000; 17 | 18 | const ANALYTICS_POLL_RETRY_BASE_DELAY_MS = 1000; 19 | const ANALYTICS_POLL_RETRY_MAX_DELAY_MS = 4000; 20 | 21 | export enum ReservedConnId { 22 | Discovery = 0, 23 | Max = 16, 24 | } 25 | 26 | const defaultAsleep = asleep; 27 | const defaultRandUint32 = ( 28 | reserved: number, 29 | ): number => { 30 | // TODO: remove this in the next protocol version by not having a reserved conn id. 31 | let randomNumber: number; 32 | do { 33 | const buf = new Uint32Array(1); 34 | crypto.getRandomValues(buf); 35 | randomNumber = buf[0]; 36 | } while (randomNumber >= 0 && randomNumber < reserved); 37 | return randomNumber; 38 | }; 39 | const defaultIsRecoverable = (_err: unknown) => true; 40 | 41 | // This is a processing queue that can handle unreliable and reliable messages. 42 | // The processing prioritizes unreliable messages over reliable messages. 43 | // Reliable messages will be always deduplicated, unreliable messages will not be deduped. 44 | class Queue { 45 | private map: Map; 46 | private emitted: Map; 47 | private unreliable: Message[]; 48 | private processing: boolean; 49 | private readonly logger: Logger; 50 | public onmsg = async (_: Message) => { }; 51 | 52 | constructor(logger: Logger) { 53 | this.logger = logger.sub("queue"); 54 | this.map = new Map(); 55 | this.emitted = new Map(); 56 | this.unreliable = []; 57 | this.processing = false; 58 | } 59 | 60 | enqueue(msg: Message) { 61 | if (!msg.header?.reliable) { 62 | this.unreliable.push(msg); 63 | } else { 64 | const seqnum = msg.header!.seqnum; 65 | if (this.map.has(seqnum) || this.emitted.has(seqnum)) return; 66 | this.map.set(seqnum, [performance.now(), msg]); 67 | } 68 | 69 | // TODO: control queue size by pruning old messages. 70 | this.processNext(); 71 | } 72 | 73 | async processNext() { 74 | if (this.processing) return; 75 | 76 | let msg = this.unreliable.pop(); 77 | if (!msg) { 78 | const res = this.map.entries().next().value; 79 | if (!res) return; 80 | 81 | const [key, value] = res; 82 | this.map.delete(key); 83 | this.emitted.set(key, value); 84 | const [_, m] = value; 85 | if (!m.header) return; 86 | msg = m; 87 | } 88 | 89 | this.processing = true; 90 | try { 91 | await this.onmsg(msg); 92 | } catch (err) { 93 | const obj: Record = { msg }; 94 | if (err instanceof Error) { 95 | obj["err"] = err; 96 | } 97 | this.logger.error("error processing message", obj); 98 | } 99 | this.processing = false; 100 | this.processNext(); 101 | } 102 | } 103 | 104 | export interface TransportOptions { 105 | readonly enableDiscovery: boolean; 106 | readonly groupId: string; 107 | readonly peerId: string; 108 | readonly logger: Logger; 109 | readonly asleep?: typeof defaultAsleep; 110 | readonly randUint32?: typeof defaultRandUint32; 111 | readonly isRecoverable?: typeof defaultIsRecoverable; 112 | } 113 | 114 | export class Transport { 115 | public readonly info: PeerInfo; 116 | private streams: Stream[]; 117 | private abort: AbortController; 118 | public readonly logger: Logger; 119 | public readonly asleep: typeof defaultAsleep; 120 | private readonly randUint32: typeof defaultRandUint32; 121 | private readonly isRecoverable: typeof defaultIsRecoverable; 122 | public onstream = (_: Stream) => { }; 123 | public onclosed = (_reason: string) => { }; 124 | 125 | constructor( 126 | private readonly client: ISignalingClient, 127 | public readonly opts: TransportOptions, 128 | ) { 129 | this.asleep = opts.asleep || defaultAsleep; 130 | this.randUint32 = opts.randUint32 || defaultRandUint32; 131 | this.isRecoverable = opts.isRecoverable || defaultIsRecoverable; 132 | 133 | this.info = { 134 | groupId: opts.groupId, 135 | peerId: opts.peerId, 136 | connId: this.randUint32(ReservedConnId.Max), 137 | }; 138 | this.abort = new AbortController(); 139 | this.logger = opts.logger.sub("transport", { 140 | info: this.info, 141 | }); 142 | this.streams = []; 143 | } 144 | 145 | async listen() { 146 | const rpcOpt: RpcOptions = { 147 | abort: this.abort.signal, 148 | timeout: POLL_TIMEOUT_MS, 149 | }; 150 | const retryOpt: RetryOptions = { 151 | baseDelay: POLL_RETRY_BASE_DELAY_MS, 152 | maxDelay: POLL_RETRY_MAX_DELAY_MS, 153 | maxRetries: -1, 154 | abortSignal: this.abort.signal, 155 | isRecoverable: this.isRecoverable, 156 | }; 157 | 158 | while (!this.abort.signal.aborted) { 159 | try { 160 | await retry(async () => { 161 | const recvStream = this.client.recv({ 162 | src: this.info, 163 | }, rpcOpt); 164 | 165 | recvStream.responses.onMessage((m) => 166 | !!m.msg && this.handleMessages(m.msg) 167 | ); 168 | await recvStream; 169 | }, retryOpt); 170 | } catch (err) { 171 | this.logger.error("unrecoverable error, force closing", { err }); 172 | this.close(); 173 | return; 174 | } 175 | } 176 | this.logger.debug("poll loop is closed"); 177 | } 178 | 179 | async close(reason?: string) { 180 | if (this.abort.signal.aborted) return; 181 | reason = reason || "transport is closed"; 182 | await Promise.all(this.streams.map((s) => s.close(reason))); 183 | // Give a chance for graceful shutdown before aborting the connection 184 | this.abort.abort(reason); 185 | this.logger.debug("transport is now closed", { reason }); 186 | this.streams = []; 187 | this.onclosed(reason); 188 | } 189 | 190 | private handleControlMessage = (payload: MessagePayload) => { 191 | switch (payload.payloadType.oneofKind) { 192 | case "ping": 193 | this.logger.debug("received ping"); 194 | break; 195 | default: 196 | this.logger.warn("received unknown control message", { payload }); 197 | break; 198 | } 199 | }; 200 | 201 | private handleMessages = (msg: Message) => { 202 | this.logger.debug("received", { msg: msg }); 203 | if (this.abort.signal.aborted) return; 204 | if (!msg.header) { 205 | if (!msg.payload) return; 206 | return this.handleControlMessage(msg.payload); 207 | } 208 | const src = msg.header.src; 209 | const dst = msg.header.dst; 210 | if (!src || !dst) return; 211 | 212 | if ( 213 | dst.connId >= ReservedConnId.Max && 214 | dst.connId != this.info.connId 215 | ) { 216 | this.logger.warn( 217 | "received messages from a stale connection, ignoring", 218 | { receivedConnID: dst.connId }, 219 | ); 220 | return; 221 | } 222 | 223 | let stream: Stream | null = null; 224 | for (const s of this.streams) { 225 | if ( 226 | src.groupId === s.other.groupId && 227 | src.peerId === s.other.peerId && 228 | src.connId === s.other.connId 229 | ) { 230 | stream = s; 231 | break; 232 | } 233 | } 234 | 235 | if (!stream) { 236 | // if (msg.payload?.payloadType.oneofKind !== "join") { 237 | // this.logger.warn( 238 | // `session not found, but non-join from ${src.peerId}:${src.connId}, dropping as this is likely staled.`, 239 | // ); 240 | // return; 241 | // } 242 | // 243 | if (src.peerId == this.info.peerId) { 244 | this.logger.warn("loopback detected, ignoring messages"); 245 | return; 246 | } 247 | 248 | this.logger.debug( 249 | `session not found, creating one for ${src.peerId}:${src.connId}`, 250 | ); 251 | 252 | stream = new Stream( 253 | this, 254 | this.info, 255 | src, 256 | this.logger, 257 | ); 258 | this.streams.push(stream); 259 | this.onstream(stream); 260 | } 261 | 262 | stream.enqueue(msg); 263 | }; 264 | 265 | removeStream(stream: Stream) { 266 | this.streams = this.streams.filter((s) => s !== stream); 267 | } 268 | 269 | async connect( 270 | otherGroupId: string, 271 | otherPeerId: string, 272 | signal: AbortSignal, 273 | ) { 274 | const payload: MessagePayload = { 275 | payloadType: { 276 | oneofKind: "join", 277 | join: {}, 278 | }, 279 | }; 280 | const header: MessageHeader = { 281 | src: this.info, 282 | dst: { 283 | groupId: otherGroupId, 284 | peerId: otherPeerId, 285 | connId: ReservedConnId.Discovery, 286 | }, 287 | seqnum: 0, 288 | reliable: false, 289 | }; 290 | 291 | let found = false; 292 | const joinedSignal = joinSignals(signal, this.abort.signal); 293 | while (!joinedSignal.aborted && !found) { 294 | await this.send(joinedSignal, { 295 | header, 296 | payload, 297 | }); 298 | await this.asleep(POLL_RETRY_MAX_DELAY_MS, joinedSignal).catch(() => { }); 299 | 300 | found = !!this.streams.find((s) => 301 | s.other.groupId === otherGroupId && s.other.peerId === otherPeerId 302 | ); 303 | } 304 | } 305 | 306 | async send(signal: AbortSignal, msg: Message) { 307 | const joinedSignal = joinSignals(signal, this.abort.signal); 308 | const rpcOpt: RpcOptions = { 309 | abort: joinedSignal, 310 | timeout: POLL_TIMEOUT_MS, 311 | }; 312 | const retryOpt: RetryOptions = { 313 | baseDelay: POLL_RETRY_BASE_DELAY_MS, 314 | maxDelay: POLL_RETRY_MAX_DELAY_MS, 315 | maxRetries: 5, 316 | abortSignal: joinedSignal, 317 | isRecoverable: this.isRecoverable, 318 | }; 319 | 320 | try { 321 | const resp = await retry(async () => 322 | await this.client.send( 323 | { msg }, 324 | rpcOpt, 325 | ), retryOpt); 326 | if (resp === null) { 327 | this.logger.warn("aborted, message dropped from sending", { msg }); 328 | return; 329 | } 330 | 331 | return; 332 | } catch (err) { 333 | this.logger.error("unrecoverable error, force closing", { err }); 334 | this.close(); 335 | return; 336 | } 337 | } 338 | 339 | async reportAnalytics(event: AnalyticsReportReq) { 340 | const rpcOpt: RpcOptions = { 341 | abort: this.abort.signal, 342 | timeout: POLL_TIMEOUT_MS, 343 | }; 344 | const retryOpt: RetryOptions = { 345 | baseDelay: ANALYTICS_POLL_RETRY_BASE_DELAY_MS, 346 | maxDelay: ANALYTICS_POLL_RETRY_MAX_DELAY_MS, 347 | maxRetries: 3, 348 | abortSignal: this.abort.signal, 349 | isRecoverable: this.isRecoverable, 350 | }; 351 | 352 | try { 353 | const resp = await retry( 354 | async () => await this.client.analyticsReport(event, rpcOpt), 355 | retryOpt, 356 | ); 357 | if (resp === null) { 358 | this.logger.warn("aborted, message dropped from sending analytics", { 359 | msg: event, 360 | }); 361 | } 362 | } catch (err) { 363 | this.logger.error( 364 | "analytics backend is in unrecoverable state, dropping analytics event", 365 | { err }, 366 | ); 367 | } 368 | } 369 | } 370 | 371 | // Stream allows multiplexing on top of Transport, and 372 | // configuring order and reliability mode 373 | export class Stream { 374 | public readonly logger: Logger; 375 | private abort: AbortController; 376 | public recvq: Queue; 377 | private lastSeqnum: number; 378 | public onsignal = async (_: Signal) => { }; 379 | public onclosed = (_reason: string) => { }; 380 | 381 | constructor( 382 | private readonly transport: Transport, 383 | public readonly info: PeerInfo, 384 | public readonly other: PeerInfo, 385 | logger: Logger, 386 | ) { 387 | this.logger = logger.sub("stream", { 388 | other, 389 | }); 390 | this.abort = new AbortController(); 391 | this.recvq = new Queue(this.logger); 392 | this.recvq.onmsg = (msg) => this.handleMessage(msg); 393 | this.lastSeqnum = 0; 394 | } 395 | 396 | createSignal(...signals: AbortSignal[]): AbortSignal { 397 | return joinSignals(this.abort.signal, ...signals); 398 | } 399 | 400 | enqueue(msg: Message) { 401 | if (this.abort.signal.aborted) { 402 | this.logger.warn( 403 | "received a message in closed state, ignoring new messages.", 404 | ); 405 | return; 406 | } 407 | 408 | this.recvq.enqueue(msg); 409 | } 410 | 411 | async send(payload: MessagePayload, reliable: boolean, signal?: AbortSignal) { 412 | if (!signal) { 413 | signal = this.abort.signal; 414 | } 415 | const msg: Message = { 416 | header: { 417 | src: this.transport.info, 418 | dst: this.other, 419 | seqnum: this.lastSeqnum, 420 | reliable, 421 | }, 422 | payload: { ...payload }, 423 | }; 424 | 425 | this.lastSeqnum++; 426 | await this.transport.send(signal, msg); 427 | } 428 | 429 | private async handleMessage(msg: Message) { 430 | if (!msg.payload) { 431 | this.logger.warn("payload is missing from the stream message", { 432 | msg, 433 | }); 434 | return; 435 | } 436 | 437 | switch (msg.payload.payloadType.oneofKind) { 438 | case "bye": 439 | this.close("received bye", true); 440 | return; 441 | case "signal": 442 | this.onsignal(msg.payload.payloadType.signal); 443 | return; 444 | case "join": 445 | // nothing to do here, this just creates the session 446 | return; 447 | default: 448 | this.logger.warn("unhandled payload type", { msg }); 449 | return; 450 | } 451 | } 452 | 453 | async close(reason?: string, skipBye?: boolean) { 454 | if (this.abort.signal.aborted) return; 455 | reason = reason || "session is closed"; 456 | if (!skipBye) { 457 | // make sure to give a chance to send a message 458 | await this.send({ 459 | payloadType: { 460 | oneofKind: "bye", 461 | bye: {}, 462 | }, 463 | }, false).catch((err) => 464 | this.logger.warn("failed to send bye", { e: err }) 465 | ); 466 | } 467 | this.abort.abort(reason); 468 | this.transport.removeStream(this); 469 | this.onclosed(reason); 470 | this.logger.debug("sent bye to the other peer", { reason }); 471 | } 472 | } 473 | -------------------------------------------------------------------------------- /peer/src/util.ts: -------------------------------------------------------------------------------- 1 | /** 2 | * asleep is an async version of setTimeout with abortable signal. 3 | * the function will resolve to false when aborted, meaning the delay will 4 | * be less than the expected. 5 | */ 6 | export function asleep(ms: number, signal?: AbortSignal): Promise { 7 | return new Promise((resolve) => { 8 | const timeoutId = setTimeout(() => resolve(true), ms); 9 | 10 | // If an AbortSignal is provided, listen for the 'abort' event 11 | if (signal) { 12 | signal.addEventListener("abort", () => { 13 | clearTimeout(timeoutId); // Cancel the delay 14 | resolve(false); 15 | }); 16 | } 17 | }); 18 | } 19 | 20 | export function joinSignals(...signals: AbortSignal[]): AbortSignal { 21 | const joined = new AbortController(); 22 | 23 | const joinedAbort = () => { 24 | joined.abort(); 25 | 26 | for (const signal of signals) { 27 | signal.removeEventListener("abort", joinedAbort); 28 | } 29 | }; 30 | 31 | for (const signal of signals) { 32 | signal.addEventListener("abort", joinedAbort); 33 | } 34 | 35 | return joined.signal; 36 | } 37 | 38 | export type RetryOptions = { 39 | maxRetries: number; // Maximum retry attempts. negative means no limit, 0 means 1 try (0 retry) 40 | baseDelay: number; // Initial delay in milliseconds 41 | maxDelay: number; // Maximum delay in milliseconds 42 | jitterFactor?: number; // Jitter percentage (e.g., 0.3 for 30%) 43 | isRecoverable?: (error: unknown) => boolean; // Function to categorize recoverable errors 44 | abortSignal?: AbortSignal; 45 | }; 46 | 47 | export async function retry( 48 | asyncFunction: () => Promise, 49 | options: RetryOptions, 50 | ): Promise { 51 | const { 52 | maxRetries, 53 | baseDelay, 54 | maxDelay, 55 | jitterFactor = 0.3, 56 | isRecoverable = () => true, // Default: all errors are recoverable 57 | abortSignal, 58 | } = options; 59 | 60 | let attempt = 0; 61 | 62 | while ((attempt <= maxRetries || maxRetries < 0) && !abortSignal?.aborted) { 63 | try { 64 | return await asyncFunction(); // Execute the function 65 | } catch (error) { 66 | // Check if the error is recoverable 67 | if (!isRecoverable(error)) { 68 | throw error; // Non-recoverable error, rethrow it 69 | } 70 | 71 | attempt++; 72 | if (maxRetries >= 0 && attempt > maxRetries) { 73 | throw error; // Exceeded max retries 74 | } 75 | 76 | // Calculate delay with exponential backoff and jitter 77 | const delay = calculateDelay(attempt, baseDelay, maxDelay, jitterFactor); 78 | await asleep(delay, abortSignal).catch(() => { }); // Wait before the next attempt 79 | } 80 | } 81 | 82 | if (abortSignal?.aborted) { 83 | return null; 84 | } 85 | 86 | throw new Error("Retry failed: max retries exceeded"); // This is a fallback; should rarely occur 87 | } 88 | 89 | // Helper to calculate exponential backoff with jitter 90 | function calculateDelay( 91 | attempt: number, 92 | baseDelay: number, 93 | maxDelay: number, 94 | jitterFactor: number, 95 | ): number { 96 | const exponentialDelay = Math.min(baseDelay * 2 ** (attempt - 1), maxDelay); 97 | const jitter = Math.random() * jitterFactor * exponentialDelay; 98 | return exponentialDelay + jitter; 99 | } 100 | -------------------------------------------------------------------------------- /peer/src/vite-env.d.ts: -------------------------------------------------------------------------------- 1 | /// 2 | -------------------------------------------------------------------------------- /peer/tsconfig.json: -------------------------------------------------------------------------------- 1 | { 2 | "compilerOptions": { 3 | "target": "ES2020", 4 | "useDefineForClassFields": true, 5 | "module": "ESNext", 6 | "lib": ["ES2020", "DOM", "DOM.Iterable"], 7 | "skipLibCheck": true, 8 | 9 | /* Bundler mode */ 10 | "moduleResolution": "bundler", 11 | "allowImportingTsExtensions": true, 12 | "isolatedModules": true, 13 | "moduleDetection": "force", 14 | "noEmit": true, 15 | 16 | /* Linting */ 17 | "strict": true, 18 | "noUnusedLocals": true, 19 | "noUnusedParameters": true, 20 | "noFallthroughCasesInSwitch": true, 21 | "noUncheckedSideEffectImports": true 22 | }, 23 | "include": ["src"] 24 | } 25 | -------------------------------------------------------------------------------- /peer/vite.config.ts: -------------------------------------------------------------------------------- 1 | import { defineConfig } from "vite"; 2 | import { auth } from "@pulsebeam/demo-server"; 3 | 4 | export default defineConfig({ 5 | base: "./", 6 | server: { 7 | proxy: { 8 | "/auth": { 9 | // https://github.com/angular/angular-cli/issues/26198 10 | target: "http://127.0.0.1:5173", 11 | bypass(req, res) { 12 | // URL requires a base url... 13 | const url = new URL(req.url!, `http://${req.headers.host}`); 14 | if (url.pathname === "/auth") { 15 | try { 16 | const token = auth(url); 17 | res!.writeHead(200, { 18 | "Content-Type": "text/plain; charset=utf-8", 19 | }); 20 | res!.end(token); 21 | } catch (e) { 22 | res!.writeHead(400, { "Content-Type": "text/plain" }); 23 | res!.end("Bad Request - groupId and peerId are required"); 24 | } 25 | } 26 | }, 27 | }, 28 | }, 29 | }, 30 | }); 31 | -------------------------------------------------------------------------------- /peer/vitest.config.ts: -------------------------------------------------------------------------------- 1 | /// 2 | import { defineConfig } from "vite"; 3 | 4 | export default defineConfig({ 5 | test: { 6 | include: ["src/**/*.test.ts"], 7 | }, 8 | }); 9 | -------------------------------------------------------------------------------- /playwright.config.ts: -------------------------------------------------------------------------------- 1 | import { defineConfig, devices } from "@playwright/test"; 2 | 3 | /** 4 | * Read environment variables from file. 5 | * https://github.com/motdotla/dotenv 6 | */ 7 | // import dotenv from 'dotenv'; 8 | // import path from 'path'; 9 | // dotenv.config({ path: path.resolve(__dirname, '.env') }); 10 | 11 | /** 12 | * See https://playwright.dev/docs/test-configuration. 13 | */ 14 | export default defineConfig({ 15 | testDir: "./tests", 16 | /* Run tests in files in parallel */ 17 | fullyParallel: false, 18 | /* Fail the build on CI if you accidentally left test.only in the source code. */ 19 | forbidOnly: !!process.env.CI, 20 | /* Retry on CI only */ 21 | retries: process.env.CI ? 4 : 0, 22 | /* Opt out of parallel tests on CI. */ 23 | // workers: process.env.CI ? 1 : 1, 24 | workers: process.env.CI ? 1 : undefined, 25 | /* Reporter to use. See https://playwright.dev/docs/test-reporters */ 26 | reporter: [ 27 | ["html", "list"], 28 | ], 29 | /* Shared settings for all the projects below. See https://playwright.dev/docs/api/class-testoptions. */ 30 | use: { 31 | /* Base URL to use in actions like `await page.goto('/')`. */ 32 | // baseURL: 'http://127.0.0.1:3000', 33 | 34 | /* Collect trace when retrying the failed test. See https://playwright.dev/docs/trace-viewer */ 35 | // trace: process.env.CI ? "retain-on-failure" : 'on', 36 | trace: "retain-on-failure", 37 | }, 38 | 39 | webServer: { 40 | command: "npm run dev -w @pulsebeam/demo-react", 41 | url: "http://127.0.0.1:5173", 42 | reuseExistingServer: true, 43 | }, 44 | 45 | /* Configure projects for major browsers */ 46 | projects: [ 47 | { 48 | name: "local", 49 | use: { 50 | baseURL: "http://127.0.0.1:5173", 51 | ignoreHTTPSErrors: true, 52 | }, 53 | retries: 2, 54 | }, 55 | { 56 | name: "production", 57 | use: { 58 | baseURL: "https://meet.lukas-coding.us/", 59 | }, 60 | retries: 2, 61 | }, 62 | ], 63 | /* Run your local dev server before starting the tests */ 64 | // webServer: { 65 | // command: 'npm run start', 66 | // url: 'http://127.0.0.1:3000', 67 | // reuseExistingServer: !process.env.CI, 68 | // }, 69 | }); 70 | -------------------------------------------------------------------------------- /tests/demo-react.spec.ts: -------------------------------------------------------------------------------- 1 | import { 2 | chromium as bChromium, 3 | firefox as bFirefox, 4 | Locator, 5 | webkit as bWebkit, 6 | } from "playwright"; 7 | import { Browser, expect, type Page, test } from "@playwright/test"; 8 | 9 | // npx playwright test --list 10 | // npx playwright test --project=local --repeat-each 15 --grep "chromium_chromium disconnect and reconnect" 11 | 12 | const PULSEBEAM_BASE_URL = process.env.PULSEBEAM_BASE_URL || 13 | "https://cloud.pulsebeam.dev/grpc"; 14 | 15 | const PRESETS = { 16 | baseUrl: PULSEBEAM_BASE_URL, 17 | forceRelay: "on", 18 | mock: "on", 19 | }; 20 | 21 | function toUrl(base: string, presets: typeof PRESETS): string { 22 | return base + 23 | `?mock=${presets.mock}&baseUrl=${presets.baseUrl}&forceRelay=${presets.forceRelay}`; 24 | } 25 | 26 | // https://playwright.dev/docs/test-retries#serial-mode 27 | test.describe.configure({ mode: "serial" }); 28 | 29 | async function waitForStableVideo( 30 | page: Page, 31 | peerId: string, 32 | timeoutMs: number, 33 | delayMs = 0, 34 | ) { 35 | // return page.waitForFunction(({ peerId, durationSeconds }) => { 36 | // const video = document.querySelector(`video[data-testid=${peerId}]`) as HTMLVideoElement; 37 | // return !!video && !video.paused && video.currentTime > durationSeconds; 38 | // }, { peerId, durationSeconds }); 39 | 40 | const video = page.getByTestId(peerId); 41 | const start = performance.now(); 42 | 43 | while ((performance.now() - start) < timeoutMs) { 44 | try { 45 | expect(await video.evaluate((v: HTMLVideoElement) => v.paused)).toBe( 46 | false, 47 | ); 48 | expect(await video.evaluate((v: HTMLVideoElement) => v.ended)).toBe( 49 | false, 50 | ); 51 | expect(await video.evaluate((v: HTMLVideoElement) => v.readyState)) 52 | .toBeGreaterThanOrEqual( 53 | 3, 54 | ); 55 | await page.waitForTimeout(delayMs).catch(() => { }); 56 | return; 57 | } catch (err) { 58 | console.warn("waitForStableVideo is not stable, will try again in 1s.", { 59 | err, 60 | }); 61 | await page.waitForTimeout(1000).catch(() => { }); 62 | } 63 | } 64 | 65 | throw new Error("waitForStableVideo timeout"); 66 | } 67 | 68 | async function assertClick(btn: Locator) { 69 | await btn.click({ timeout: 1000 }).catch(() => { }); 70 | await expect(btn).not.toBeVisible(); 71 | } 72 | 73 | async function start(page: Page, groupId: string, peerId: string) { 74 | await page.getByTestId("src-groupId").fill(groupId); 75 | await page.getByTestId("src-peerId").fill(peerId); 76 | await waitForStableVideo(page, peerId, 5_000); 77 | 78 | await assertClick(page.getByTestId("btn-ready")); 79 | 80 | return () => assertClick(page.getByTestId("btn-endCall")); 81 | } 82 | 83 | function randId() { 84 | return Math.floor(Math.random() * 2 ** 32); 85 | } 86 | 87 | function getAllPairs(list: T[]): [T, T][] { 88 | const pairs: [T, T][] = []; 89 | 90 | for (let i = 0; i < list.length; i++) { 91 | for (let j = i; j < list.length; j++) { 92 | pairs.push([list[i], list[j]]); 93 | } 94 | } 95 | return pairs; 96 | } 97 | 98 | test(`load`, async ({ browser, browserName, baseURL }) => { 99 | const url = toUrl(baseURL!, PRESETS); 100 | const context = await browser.newContext(); 101 | const page = await context.newPage(); 102 | await page.goto(url); 103 | await waitForStableVideo(page, "", 1000); 104 | }); 105 | 106 | test.describe("Connect", () => { 107 | const browsers: Record = { 108 | "chromium": undefined, 109 | // "webkit": undefined, 110 | }; 111 | const pairs: [string, string][] = getAllPairs(Object.keys(browsers)); 112 | 113 | test.beforeAll(async () => { 114 | browsers["chromium"] = await bChromium.launch({}); 115 | // browsers["firefox"] = await bFirefox.launch(); 116 | // webkit still doesn't allow fake webcam 117 | // https://github.com/microsoft/playwright/issues/2973 118 | // browsers["webkit"] = await bWebkit.launch(); 119 | }); 120 | 121 | // basic connection test a->b 122 | for (const [bA, bB] of pairs) { 123 | test(`${bA}_${bB} basic connection`, async ({ baseURL }) => { 124 | const url = toUrl(baseURL!, PRESETS); 125 | const group = `${randId()}`; 126 | const peerA = `__${bA}_A`; 127 | const peerB = `__${bB}_B`; 128 | 129 | // Launch browserA for pageA 130 | const contextA = await browsers[bA]!.newContext(); 131 | const pageA = await contextA.newPage(); 132 | await pageA.goto(url); 133 | 134 | // Launch browserB for pageB 135 | const contextB = await browsers[bB]!.newContext(); 136 | const pageB = await contextB.newPage(); 137 | await pageB.goto(url); 138 | 139 | try { 140 | // Initial connection B -> A 141 | const [closeA, closeB] = await Promise.all([ 142 | start(pageB, group, peerB), 143 | start(pageA, group, peerA), 144 | ]); 145 | await Promise.all([ 146 | waitForStableVideo(pageB, peerA, 10_000), 147 | waitForStableVideo(pageA, peerB, 10_000), 148 | ]); 149 | await Promise.all([closeA(), closeB()]); 150 | } finally { 151 | await contextA.close(); 152 | await contextB.close(); 153 | } 154 | }); 155 | 156 | // Disconnect and reconnect with role reversal 157 | test(`${bA}_${bB} disconnect and reconnect`, async ({ baseURL }) => { 158 | const url = toUrl(baseURL!, PRESETS); 159 | const group = `${randId()}`; 160 | const peerA = `__${bA}_A`; 161 | const peerB = `__${bB}_B`; 162 | 163 | const contextA = await browsers[bA]!.newContext(); 164 | const pageA = await contextA.newPage(); 165 | await pageA.goto(url); 166 | 167 | const contextB = await browsers[bB]!.newContext(); 168 | const pageB = await contextB.newPage(); 169 | await pageB.goto(url); 170 | 171 | try { 172 | // Initial connection B -> A 173 | const [closeA, closeB] = await Promise.all([ 174 | start(pageA, group, peerA), 175 | start(pageB, group, peerB), 176 | ]); 177 | 178 | // End call 179 | await Promise.all([closeA(), closeB()]); 180 | 181 | // Verify streams stopped 182 | await expect(pageA.getByTestId(peerB)).toHaveCount(0); 183 | await expect(pageB.getByTestId(peerA)).toHaveCount(0); 184 | 185 | // Reconnect with reversed roles A -> B 186 | const [closeB2, closeA2] = await Promise.all([ 187 | start(pageB, group, peerB), 188 | start(pageA, group, peerA), 189 | ]); 190 | await Promise.all([ 191 | waitForStableVideo(pageB, peerA, 10_000), 192 | waitForStableVideo(pageA, peerB, 10_000), 193 | ]); 194 | 195 | await Promise.all([closeA2(), closeB2()]); 196 | } finally { 197 | await contextA.close(); 198 | await contextB.close(); 199 | } 200 | }); 201 | } 202 | }); 203 | --------------------------------------------------------------------------------