{"id":26047685,"url":"https://github.com/arcjet/gravity","last_synced_at":"2025-04-10T14:13:04.441Z","repository":{"id":279310920,"uuid":"932665335","full_name":"arcjet/gravity","owner":"arcjet","description":"Gravity is a host generator for WebAssembly Components. It currently targets Wazero, a zero dependency WebAssembly runtime for Go.","archived":false,"fork":false,"pushed_at":"2025-04-01T21:57:09.000Z","size":91,"stargazers_count":40,"open_issues_count":22,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-02T22:43:54.829Z","etag":null,"topics":["wasm","wazero","webassembly"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/arcjet.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":"2025-02-14T09:47:03.000Z","updated_at":"2025-03-28T20:46:47.000Z","dependencies_parsed_at":"2025-02-24T23:38:37.718Z","dependency_job_id":null,"html_url":"https://github.com/arcjet/gravity","commit_stats":null,"previous_names":["arcjet/gravity"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcjet%2Fgravity","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcjet%2Fgravity/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcjet%2Fgravity/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arcjet%2Fgravity/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arcjet","download_url":"https://codeload.github.com/arcjet/gravity/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248232825,"owners_count":21069490,"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":["wasm","wazero","webassembly"],"created_at":"2025-03-07T23:13:01.774Z","updated_at":"2025-04-10T14:13:04.419Z","avatar_url":"https://github.com/arcjet.png","language":"Rust","funding_links":[],"categories":["Tools"],"sub_categories":["Host Runtimes"],"readme":"\u003e [!IMPORTANT]\n\u003e This is a very early release of Gravity. Many WIT features are not yet implemented\n\u003e and the project is is likely to change significantly as we develop it further.\n\n# Gravity\n\nGravity is a host generator for WebAssembly Components. It currently targets [Wazero][wazero], a zero dependency WebAssembly runtime for Go.\n\n## What?\n\nThis crate provides the `gravity` tool—a code generator that produces Wazero\nhost code for WebAssembly Components. Currently, we only process Wasm core\nmodules with a WIT metadata custom section.\n\n## Why?\n\nMuch of Arcjet's protection rules are written in Rust \u0026 compiled to WebAssembly.\nTo allow us to use rich types at the Wasm boundary, we leverage the [WebAssembly\nInterface Type][wit] format (or WIT). Our Rust code consumes the\n[wit-bindgen][wit-bindgen] project which generates the lifting and lowering of\nthese types inside the \"guest\" WebAssembly module. However, the only way to\n\"host\" one of these WebAssembly Components is via [Wasmtime][wasmtime] or\n[jco][jco].\n\nWe were able to leverage `jco transpile` to translate our WebAssembly Components\nto Core Wasm that runs in a JavaScript environment, but we don't have easy\naccess to Wasmtime in our server environment. Most of our server logic is\nwritten in Go, which has fantastic Core Wasm support via [Wazero][wazero].\nWazero has [rejected the Component Model][wazero-component-model], but we can\nstill translate Components to Core today.\n\nBy adopting a similar strategy as `jco transpile`, we've built this tool to\nproduced Wazero output that adhere's to the Component Model's [Canonical\nABI][canonical-abi].\n\n## Installation\n\nTo produce Go files with good indentation, this tool should be installed with a\nRust nightly toolchain. You can install one with:\n\n```bash\nrustup toolchain install nightly-2025-01-01\n```\n\nFrom inside this directory, you can install using the command:\n\n```bash\ncargo +nightly-2025-01-01 install --path .\n```\n\nOr alternatively, you can install the latest published version from crates.io\nusing this command:\n\n```bash\ncargo +nightly-2025-01-01 install arcjet-gravity\n```\n\n## Usage\n\nTo generate the bindings, you run something like:\n\n```bash\ngravity example/example.wasm --world example --output example/example.go\n```\n\nAfter you generate the code, you'll want to ensure you have all the necessary\ndependencies. You can run:\n\n```bash\ngo mod tidy\n```\n\n## Example\n\nAn runnable example in our [examples/](./examples/) directory. Please see the\n[README](./examples/README.md) for instructions on running it.\n\n## Status\n\n\nCurrently, that means we support:\n\n- `string`\n- `u32`\n- `result\u003cstring, string\u003e`\n- `result\u003c_, string\u003e`\n- `option\u003cstring\u003e`\n\nThis list is likely to grow quickly, as one of our goals is to avoid working\nwith JSON serialized as a string and instead leverage more concrete types that\nwe can codegen.\n\n## Output\n\nThe generated output consists of a bindings file and a Wasm file which\nis placed next to it. The bindings file loads the Wasm file using `go:embed`.\n\nAlternatively, if you set the `inline-wasm` flag Gravity will output the Wasm\nfile contents encoded as hex if you wish to avoid using `go:embed`. This will likely\nresult in much larger file sizes.\n\nWe produce a \"factory\" and \"instance\" per world. Given an `example` world:\n\n```txt\npackage arcjet:example;\n\ninterface logger {\n  debug: func(msg: string);\n  log: func(msg: string);\n  warn: func(msg: string);\n  error: func(msg: string);\n}\n\nworld example {\n  import logger;\n\n  export foobar: func() -\u003e result\u003cstring, string\u003e;\n}\n```\n\nThe generated code will define the `ExampleFactory` and `ExampleInstance`. Generally,\nthe factory is constructed once upon startup because it prepares all of the\nimports and compiles the WebAssembly, which can take a long time. In the example\nabove, the `ExampleFactory` can be constructed with `NewExampleFactory` which is\nprovided with a `context.Context` and a type implementing the `IExampleLogger`\ninterface.\n\nAny interfaces defined as imports to the world will have a corresponding\ninterface definition in Go, as we saw the `IExampleLogger` above. This defines the\nhigh-level functions that must be available to call from Wasm. The `logger`\ninterface was translated to:\n\n```go\ntype IExampleLogger interface {\n  Debug(ctx context.Context, msg string)\n  Log(ctx context.Context, msg string)\n  Warn(ctx context.Context, msg string)\n  Error(ctx context.Context, msg string)\n}\n```\n\nFactories can produce instances using the `Instantiate` function, which only\ntakes a `context.Context`. This function prepares the WebAssembly to be executed\nbut is generally very fast, since the factory pre-compiles the Wasm module.\n\nExported functions are called on an instance, such as our `foobar` function. You\nwould call this like\n`inst.Foobar(ctx)`. Since\nthe return value is defined as a `result\u003cstring, string\u003e`, it is translated into\nthe idiomatic Go return type `(string, error)`.\n\nWhen you are done with an instance, you are expected to call `Close` but you'll\nprobably just want to `defer` it, like `defer inst.Close(ctx)`.\n\n### Testing\n\nConsuming the generated bindings should be pretty straightforward. As such,\nwriting a test for the above would look something like:\n\n```go\npackage example\n\nimport (\n  \"context\"\n  \"testing\"\n\n  \"github.com/stretchr/testify/require\"\n)\n\nfunc Test_Generated_Example(t *testing.T) {\n  // Assuming you've generated mocks with Mockery\n  logger := NewMockIBotsLogger(t)\n  ctx := context.Background()\n  factory, err := NewExampleFactory(ctx, logger)\n  require.NoError(t, err)\n\n  instance, err := factory.Instantiate(ctx)\n  require.NoError(t, err)\n  defer instance.Close(ctx)\n\n  result, err := instance.Foobar(ctx)\n  require.NoError(t, err)\n  require.NotEqual(t, result, \"\")\n}\n```\n\n[wit]: https://github.com/WebAssembly/component-model/blob/a74225c12c152df59f745cfc0fbde79b5310ccd9/design/mvp/WIT.md\n[wit-bindgen]: https://github.com/bytecodealliance/wit-bindgen\n[wasmtime]: https://wasmtime.dev/\n[jco]: https://github.com/bytecodealliance/jco\n[wazero]: https://github.com/tetratelabs/wazero\n[canonical-abi]: https://github.com/WebAssembly/component-model/blob/a74225c12c152df59f745cfc0fbde79b5310ccd9/design/mvp/CanonicalABI.md\n[wazero-component-model]: https://github.com/tetratelabs/wazero/issues/2200\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcjet%2Fgravity","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farcjet%2Fgravity","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farcjet%2Fgravity/lists"}