{"id":21531945,"url":"https://github.com/matrixai/js-quic","last_synced_at":"2025-04-10T00:29:12.469Z","repository":{"id":63597452,"uuid":"564149954","full_name":"MatrixAI/js-quic","owner":"MatrixAI","description":"QUIC Networking for TypeScript \u0026 JavaScript","archived":false,"fork":false,"pushed_at":"2024-06-28T04:44:17.000Z","size":2328,"stargazers_count":10,"open_issues_count":9,"forks_count":2,"subscribers_count":4,"default_branch":"staging","last_synced_at":"2024-06-29T09:09:59.167Z","etag":null,"topics":["http3","network-programming","peer-to-peer","quic"],"latest_commit_sha":null,"homepage":"https://polykey.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatrixAI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-11-10T05:00:02.000Z","updated_at":"2024-07-08T03:28:23.375Z","dependencies_parsed_at":"2024-03-18T01:49:35.557Z","dependency_job_id":"7de9d6ed-0507-4ce6-9f91-fd5fb1b6692b","html_url":"https://github.com/MatrixAI/js-quic","commit_stats":null,"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-quic","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-quic/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-quic/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatrixAI%2Fjs-quic/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatrixAI","download_url":"https://codeload.github.com/MatrixAI/js-quic/tar.gz/refs/heads/staging","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226116124,"owners_count":17575948,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["http3","network-programming","peer-to-peer","quic"],"created_at":"2024-11-24T02:18:17.499Z","updated_at":"2025-04-10T00:29:12.448Z","avatar_url":"https://github.com/MatrixAI.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# js-quic\n\nQUIC library for TypeScript/JavaScript applications.\n\nThis is built on top of Cloudflare's [quiche](https://github.com/cloudflare/quiche) library. It is intended to support Linux, Windows MacOS, Android and iOS. Mobile support is still pending.\n\nSince Cloudflare's quiche is written in Rust. This uses the [napi-rs](https://github.com/napi-rs/napi-rs) binding system compile the native objects for Node.js.\n\nThis library focuses only on the QUIC protocol. It does not support HTTP3. You can build HTTP3 on top of this.\n\n## Installation\n\n```sh\nnpm install --save @matrixai/quic\n```\n\n## Usage\n\nSee the example usage in [tests](tests).\n\n## Development\n\nRun `nix develop`, and once you're inside, you can use:\n\n```sh\n# install (or reinstall packages from package.json)\nnpm install\n# build the native objects\nnpm run prebuild\n# build the dist and native objects\nnpm run build\n# run the repl (this allows you to import from ./src)\nnpm run tsx\n# run the tests\nnpm run test\n# lint the source code\nnpm run lint\n# automatically fix the source\nnpm run lintfix\n```\n\n### Docs Generation\n\n```sh\nnpm run docs\n```\n\nSee the docs at: https://matrixai.github.io/js-quic/\n\n### Publishing\n\n```sh\n# npm login\nnpm version patch # major/minor/patch\nnpm run build\nnpm publish --access public\ngit push\ngit push --tags\n```\n\n## How it works\n\n### Quiche\n\nTo understand how to develop this, it is important to understand how quiche works.\n\nClone the https://github.com/cloudflare/quiche project. It's multi-workspace Cargo project.\n\nYou can build and run their examples located in `/quiche/examples/`:\n\n```sh\ncargo build --examples\ncargo run --example client '127.0.0.1:55555'\n```\n\nYou can run their apps located in `/apps/src/bin`:\n\n```sh\ncd /apps\n\n# The source code for these is in the `/apps/src/bin` directory\ncargo run --bin quiche-client -- https://cloudflare-quic.com\n\n# Run with\ncargo run --bin quiche-server -- --listen 127.0.0.1:55555\n\n# Run without verifying TLS if certificates is\ncargo run --bin quiche-client -- --no-verify 'http://127.0.0.1:55555'\n```\n\n### TLS\n\nIf you need to test with a local certificates, try using `step`;\n\n```sh\nstep certificate create \\\n  localhost localhost.crt localhost.key \\\n  --profile self-signed \\\n  --subtle \\\n  --no-password \\\n  --insecure \\\n  --force \\\n  --san 127.0.0.1 \\\n  --san ::1 \\\n  --not-after 31536000s\n\n# Afterwards put certificates in `./tmp` and refer to them\n```\n\n### Cargo/Rust targets\n\nCargo is a cross-compiler. The target structure looks like this:\n\n```\n\u003carch\u003e\u003csub\u003e-\u003cvendor\u003e-\u003csys\u003e-\u003cabi\u003e\n```\n\nFor example:\n\n```\nx86_64-unknown-linux-gnu\nx86_64-pc-windows-msvc\naarch64-apple-darwin\nx86_64-apple-darwin\n```\n\nThe available target list is in `rustc --print target-list`.\n\n### Structure\n\nIt is possible to structure the QUIC system in the encapsulated way or the injected way.\n\nWhen using the encapsulated way, the `QUICSocket` is separated between client and server.\n\nWhen using the injected way, the `QUICSocket` is shared between client and server.\n\n![image](/images/quic_structure_encapsulated.svg)\n\nIf you are building a peer to peer network, you must use the injected way. This is the only way to ensure that hole-punching works because both the client and server for any given peer must share the same UDP socket and thus share the `QUICSocket`. When done in this way, the `QUICSocket` lifecycle is managed outside of both the `QUICClient` and `QUICServer`.\n\n![image](/images/quic_structure_injected.svg)\n\nThis also means both `QUICClient` and `QUICServer` must share the same connection map.  In order to allow the `QUICSocket` to dispatch data into the correct connection, the connection map is constructed in the `QUICSocket`, however setting and unsetting connections is managed by `QUICClient` and `QUICServer`.\n\n### Dataflow\n\nThe data flow of the QUIC system is a bidirectional graph.\n\nData received from the outside world is received on the UDP socket. It is parsed and then dispatched to each `QUICConnection`. Each connection further parses the data and then dispatches to the `QUICStream`. Each `QUICStream` presents the data on the `ReadableStream` interface, which can be read by a caller.\n\nData sent to the outside world is written to a `WritableStream` interface of a `QUICStream`. This data is buffered up in the underlying Quiche stream. A send procedure is triggered on the associated `QUICConnection` which takes all the buffered data to be sent for that connection, and sends it to the `QUICSocket`, which then sends it to the underlying UDP socket.\n\n![image](/images/quic_dataflow.svg)\n\nBuffering occurs at the connection level and at the stream level. Each connection has a global buffer for all streams, and each stream has its own buffer. Note that connection buffering and stream buffering all occur within the Quiche library. The web streams `ReadableStream` and `WritableStream` do not do any buffering at all.\n\n### Connection Negotiation\n\nThe connection negotiation process involves several exchanges of QUIC packets before the `QUICConnection` is constructed.\n\nThe primary reason to do this is for both sides to determine their respective connection IDs.\n\n![image](/images/quic_connection_negotiation.svg)\n\n### Push \u0026 Pull\n\nThe `QUICSocket`, `QUICClient`, `QUICServer`, `QUICConnection` and `QUICStream` are independent state machines that exposes methods that can be called as well as events that may be emitted between them.\n\nThis creates a concurrent decentralised state machine system where there are multiple entrypoints of change.\n\nUsers may call methods which causes state transitions internally that trigger event emissions. However some methods are considered internal to the library, this means these methods are not intended to be called by the end user. They are however public relative to the other components in the system. These methods should be marked with `@internal` documentation annotation.\n\nExternal events may also trigger event handlers that will call methods which perform state transitions and event emission.\n\nKeeping track of how the system works is therefore quite complex and must follow a set of rules.\n\n* Pull methods - these are either synchronous or asynchronous methods that may throw exceptions.\n* Push handlers - these are event handlers that can initiate pull methods, if these pull handlers throw exceptions, these exceptions must be caught, and expected runtime exceptions are to be converted to error events, all other exceptions will be considered to be software bugs and will be bubbled up to the program boundary as unhandled exceptions or unhandled promise rejections. Generally the only exceptions that are expected runtime exceptions are those that arise from perform IO with the operating system.\n\n## License\n\njs-quic is licensed under Apache-2.0, you may read the terms of the license [here](LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fjs-quic","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrixai%2Fjs-quic","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrixai%2Fjs-quic/lists"}