{"id":13615955,"url":"https://github.com/dylibso/wasmstore","last_synced_at":"2025-04-30T21:51:13.672Z","repository":{"id":167305533,"uuid":"551603726","full_name":"dylibso/wasmstore","owner":"dylibso","description":"A content-addressable datastore for WebAssembly modules","archived":false,"fork":false,"pushed_at":"2024-09-30T22:01:46.000Z","size":1225,"stargazers_count":54,"open_issues_count":2,"forks_count":1,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-17T01:25:05.511Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dylibso.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-10-14T18:14:22.000Z","updated_at":"2025-01-07T05:14:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"cede962d-3f40-4e15-83b5-458ef8540586","html_url":"https://github.com/dylibso/wasmstore","commit_stats":null,"previous_names":["dylibso/wasmstore"],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fwasmstore","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fwasmstore/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fwasmstore/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylibso%2Fwasmstore/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dylibso","download_url":"https://codeload.github.com/dylibso/wasmstore/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251789308,"owners_count":21644081,"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":[],"created_at":"2024-08-01T20:01:21.205Z","updated_at":"2025-04-30T21:51:13.651Z","avatar_url":"https://github.com/dylibso.png","language":"OCaml","funding_links":[],"categories":["OCaml"],"sub_categories":[],"readme":"# wasmstore\n\n[![Latest github release](https://img.shields.io/github/v/release/dylibso/wasmstore?include_prereleases\u0026label=latest)](https://github.com/dylibso/wasmstore/releases/latest)\n[![npm](https://img.shields.io/npm/v/@dylibso/wasmstore)](https://www.npmjs.com/package/@dylibso/wasmstore)\n[![pypi](https://img.shields.io/pypi/v/wasmstore)](https://pypi.org/project/wasmstore/)\n[![crates.io](https://img.shields.io/crates/v/wasmstore-client)](https://crates.io/crates/wasmstore-client)\n\nA content-addressable store for WASM modules\n\n- Built-in WASM validation\n- History management, branching and merging\n- Command-line interface\n- HTTP interface\n  - Simple authentication with roles based on HTTP request methods\n  - Optional SSL\n\n## Overview\n\n- WebAssembly modules are identified by their `hash` and are associated with a `path`, similar to a path on disk\n  - Storing modules based on their hashes allows wasmstore to de-duplicate identical modules\n  - Paths make it possible to give modules custom names\n- Any time the store is modified a `commit` is created\n  - Commits can be identified by a hash and represent a checkpoint of the store\n  - Contains some additional metadata: author, message and timestamp\n- Every time an existing `path` is updated a new `version` is created automatically\n  - `rollback` reverts a path to the previous version\n  - `restore` reverts to any prior `commit`\n  - `versions` lists the history for a path, including module hashses and commit hashes\n- A `branch` can be helpful for testing, to update several paths at once or for namespacing\n  - The `main` branch is the default, but it's possible to create branches with any name \n  - `snapshot` gets the current `commit` hash\n  - `merge` is used to merge a `branch` into another\n\n## Building\n\n### Docker\n\nThere is a `Dockerfile` at the root of the repository that can be used to build and run the `wasmstore` server:\n\n```shell\n$ docker build -t wasmstore .\n$ docker run -it -p 6384:6384 wasmstore\n```\n\n## Pull from registry (Docker Hub or GitHub Registry)\n```sh\n$ docker pull dylibso/wasmstore\n$ docker run --rm -it -p 6384:6384 dylibso/wasmstore\n```\n\n### Opam\n\nThe `wasmstore` executable contains the command-line interface and the server, to build it you will need [opam](https://opam.ocaml.org)\ninstalled.\n\n```shell\n$ opam install . --deps-only\n$ dune build\n$ dune exec ./bin/main.exe --help\n```\n\n`wasmstore` can also be built using [opam-monorepo](https://github.com/tarides/opam-monorepo):\n\n```shell\n$ opam repository add dune-universe git+https://github.com/dune-universe/opam-overlays.git\n$ opam install opam-monorepo\n$ opam monorepo pull\n$ dune build ./bin\n$ dune exec ./bin/main.exe --help\n```\n\n## Installation\n\nOnce `wasmstore` has been built it can be installed with:\n\n```sh\n$ make PREFIX=/usr/local install\n```\n\n## HTTP Interface\n\nThe server can be started using the `wasmstore` executable:\n\n```sh\n$ wasmstore server\n```\n\nor `docker-compose`:\n\n```sh\n$ docker-compose up\n```\n\nAll endpoints except the `/branch` endpoints accept a header named `Wasmstore-Branch`\nthat will cause the call to modify the specified branch instead of the default\nbranch.\n\n- `GET /api/v1/modules/*`\n  - Returns a JSON object mapping module paths to their hashes for the\n    specified path\n  - Example: `curl http://127.0.0.1:6384/api/v1/modules`\n- `GET /api/v1/module/*`\n  - Get a single module by hash or path, the module hash will also be stored in\n    the `Wasmstore-Hash` header in the response.\n  - Example: `curl http://127.0.0.1:6384/api/v1/module/mymodule.wasm`\n- `HEAD /api/v1/module/*`\n  - Returns `200` status code if the path exists, otherwise `404`\n- `POST /api/v1/module/*`\n  - Add a new module, the request body should contain the WASM module\n  - Example: `curl --data-binary @mymodule.wasm http://127.0.0.1:6384/api/v1/module/mymodule.wasm`\n- `DELETE /api/v1/module/*`\n  - Delete a module by hash or path\n- `GET /api/v1/hash/*`\n  - Get the hash of the module stored at a specific path\n- `POST /api/v1/hash/:hash/*`\n  - Set the path to point to the provided hash (the hash should already exist in the store)\n- `PUT /api/v1/branch/:branch`\n  - Switch the default branch\n- `POST /api/v1/branch/:branch`\n  - Create a new branch\n- `DELETE /api/v1/branch/:branch`\n  - Delete a branch\n- `GET /api/v1/branch`\n  - Return the name of the default branch\n- `GET /api/v1/branches`\n  - Return a JSON array of active branch names\n- `POST /api/v1/gc`\n  - Run garbage collection\n- `POST /api/v1/merge/:branch`\n  - Merge the specified branch into the default branch\n- `POST /api/v1/restore/:hash/*`\n  - Revert to the specified commit hash\n  - It's possible to revert the entire tree or a single path \n- `POST /api/v1/rollback/*`\n  - Revert to the last commit\n  - This can also be used to revert the entire tree or a single path\n- `GET /api/v1/snapshot`\n  - Returns the latest commit hash\n- `GET /api/v1/commit/:hash`\n  - Returns a JSON object with information about a commit\n- `GET /api/v1/versions/*`\n  - Returns an array of pairs (module hash, commit hash) of all previous modules stored at the provided path\n- `GET /api/v1/version/:index/*`\n  - Returns a previous version of a module at the provided path\n- `GET /api/v1/watch`\n  - A WebSocket endpoint that sends updates about changes to the store to the client\n- `* /api/v1/auth`\n  - This endpoint can be used with any method to check capabilities for an authentication secret\n\nThere are existing clients for [Rust](https://github.com/dylibso/wasmstore/tree/main/client/rust), [Javascript](https://github.com/dylibso/wasmstore/tree/main/client/js)\n[Python](https://github.com/dylibso/wasmstore/tree/main/client/python) and [Go](https://github.com/dylibso/wasmstore/tree/main/client/go)\n\n### Authentication\n\nUsing the `wasmstore server --auth` flag or the `WASMSTORE_AUTH` environment variable you can restrict certain authentication keys\nto specific request methods:\n\n```sh\n$ wasmstore server --auth \"MY_SECRET_KEY:GET,POST;MY_SECRET_READONLY_KEY:GET\"\n$ WASMSTORE_AUTH=\"MY_SECRET_KEY:GET,POST;MY_SECRET_READONLY_KEY:GET\" wasmstore server\n```\n\nOn the client side you should supply the key using the `Wasmstore-Auth` header\n\n## Command line\n\nSee the output of `wasmstore --help` for a full list of commands\n\n### Examples\n\nAdd a file from disk\n\n```sh\n$ wasmstore add /path/to/myfile.wasm\n```\n\nGet module using hash:\n\n```sh\n$ wasmstore find \u003cMODULE HASH\u003e\n```\n\nGet module using path:\n\n```sh\n$ wasmstore find myfile.wasm\n```\n\nCreate a new branch:\n\n```sh\n$ wasmstore branch my-branch\n```\n\nAdd module to non-default branch\n\n```sh\n$ wasmstore add --branch my-branch /path/to/another-file.wasm\n```\n\nMerge a branch into the main branch\n\n```sh\n$ wasmstore merge my-branch\n```\n\nDelete a branch\n\n```sh\n$ wasmstore branch my-branch --delete\n```\n\nGet the current commit hash:\n\n```sh\n$ wasmstore snapshot\n```\n\nRestore to a prior commit:\n\n```sh\n$ wasmstore restore \u003cCOMMIT HASH\u003e\n```\n\nRun garbage collection:\n\n```sh\n$ wasmstore gc\n```\n\nExport the main branch to a directory on disk:\n\n```sh\n$ wasmstore export -o ./wasm-modules\n```\n\nBackup the entire database:\n\n```sh\n$ wasmstore backup backup.tar.gz\n```\n\nTo create a new store from a backup:\n\n```sh\n$ mkdir $WASMSTORE_ROOT\n$ cd $WASMSTORE_ROOT\n$ tar xzf /path/to/backup.tar.gz\n```\n\n## A note on garbage collection\n\nWhen the gc is executed for a branch all prior commits are squashed into one\nand all non-reachable objects are removed. For example, if an object is still\nreachable from another branch it will not be deleted. Because of this, running\nthe garbage collector may purge prior commits, potentially causing `restore`\nto fail.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylibso%2Fwasmstore","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdylibso%2Fwasmstore","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylibso%2Fwasmstore/lists"}