Skip to content

Commit 22c974f

Browse files
authored
Update README with new section on fallback registries. (#200)
* add explanation link to .well-known concept * add sub-section on default fallback registries
1 parent 6877a49 commit 22c974f

1 file changed

Lines changed: 23 additions & 3 deletions

File tree

README.md

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -142,14 +142,18 @@ config_file = "/a/path"
142142
auth = { username = "open", password = "sesame" }
143143
```
144144

145-
### Well-known metadata
145+
### Metadata via Well-known URI (`/.well-known`)
146146

147-
For well-used or public registries, we recommend creating a well-known metadata file that is used by
147+
For well-used or public registries, we recommend creating a [well-known metadata file](https://en.wikipedia.org/wiki/Well-known_URI) that is used by
148148
the tool chain to simplify configuration and indicate to a client which protocols and mappings to
149149
use (although this can be set directly in config as well). The `wkg` tool and libraries expect a
150150
`registry.json` file to be present at a specific location to indicate to the tooling where the
151151
components are stored. For example, if a registry was `example.com`, then the tooling will attempt
152-
to find a `registry.json` file at `https://example.com/.well-known/wasm-pkg/registry.json`.
152+
For well-used or public registries, we recommend creating a [`.well-known` metadata file](https://en.wikipedia.org/wiki/Well-known_URI) that is used by
153+
the tool chain to simplify configuration and indicate to a client which protocols and mappings to
154+
use (although this can be set directly in config as well).
155+
156+
The `wkg` tool and libraries expect a `registry.json` file to be present at a specific location to indicate to the tooling where the components are stored. For example, given a registry `example.com`, then the tooling will attempt to find a `registry.json` file at `https://example.com/.well-known/wasm-pkg/registry.json`.
153157

154158
A full example of what this `registry.json` file should look like is below:
155159

@@ -208,6 +212,22 @@ file from the example above, then the component will be stored at
208212
`ghcr.io/webassembly/acme/foo:0.1.0`. Please note that the tag _MUST_ be a valid semantic version or
209213
the tooling will ignore it when pulling.
210214

215+
### Default fallback registries
216+
217+
If no configuration is found, the following mapping of namespace prefixes is used as a fallback:
218+
```
219+
wasi = "wasi.dev"
220+
ba = "bytecodealliance.org"
221+
```
222+
The `wkg` tool will therefore fetch registry metadata from the respective [well-known URIs](https://en.wikipedia.org/wiki/Well-known_URI):
223+
```
224+
https://wasi.dev/.well-known/wasm-pkg/registry.json
225+
https://bytecodealliance.org/.well-known/wasm-pkg/registry.json
226+
```
227+
Both registries store their packages as OCI artifacts in the GitHub Container Registry [ghcr.io](ghcr.io).
228+
229+
230+
211231
## `wkg.toml` and `wkg.lock`
212232

213233
Whenever `wkg` is used to fetch dependencies or build a wit package, it will automatically create a

0 commit comments

Comments
 (0)