~ivilata/gwit-spec

252edb8e0c72fda9bda086a712907e4a6d55d484 — Ivan Vilata-i-Balaguer 3 months ago 8acaf80
Well-Known URIs: clarify to which protocol belong URI and site root.

Especially, try to avoid suggesting that `.well-known/gwit.ini` should be
placed under the root of the gwit site (unless it is the same as the root used
by the other protocol, of course).
1 files changed, 3 insertions(+), 3 deletions(-)

M README.md
M README.md => README.md +3 -3
@@ 358,9 358,9 @@ When producing or displaying contents on URI retrieval, the gwit client MAY make

One of gwit's goals is to make existing Web or Gemini static sites easy to publish in parallel as gwit sites. This may be as simple as distributing site files in a Git repository, along with `_gwit/self.key` and `_gwit/self.ini` files, and using the key in `_gwit/self.key` to sign commits.

For a more seamless integration, it should be possible to use the other protocols supported by such a **combined site** to both identify it as such and get the information needed to access it over gwit. However, since the `_gwit` directory is always found in the Git repository's top directory, if the site is configured to use a different root directory (i.e. `site.<ID>.root` in `_gwit/self.ini`), those files may not be available via URIs.
For a more seamless integration, it should be possible to use the other protocols supported by such a **combined site** to both identify it as such and get the information needed to then access it over gwit. This information may be found in the files in the `_gwit` directory. However, since this is always found in the Git repository's top directory, if the site is configured in the other protocol to use some subdirectory `<SITE-ROOT>` as a root, those files may not be available via the other protocol's URIs.

A Well-Known URI ([RFC8615][]) MAY be used to provide such site metadata, accessible via the `/.well-known/gwit.ini` URI path, mapping to the repository file `<SITE-ROOT>/.well-known/gwit.ini`. The format and features of this file are those of a site introduction file (see further above), where the site introduces itself. The file MUST contain exactly one `[site "<ID>"]` subsection. As with any introduction, the only truly relevant pieces of information are the site ID and the value(s) of `site.<ID>.remote` (e.g. `git config -f … --get-regexp '^site\.0x[0-9a-f]+\.remote$'`).
A Well-Known URI ([RFC8615][]) MAY be used to provide such site metadata, accessible via the other protocol's `/.well-known/gwit.ini` URI path, mapping to the repository file `<SITE-ROOT>/.well-known/gwit.ini`. The format and features of this file are those of a site introduction file (see further above), where the site introduces itself. The file MUST contain exactly one `[site "<ID>"]` subsection. As with any introduction, the only truly relevant pieces of information are the site ID and the value(s) of `site.<ID>.remote` (e.g. `git config -f … --get-regexp '^site\.0x[0-9a-f]+\.remote$'`).

[RFC8615]: https://www.rfc-editor.org/rfc/rfc8615.html
    "Well-Known Uniform Resource Identifiers (URIs) (RFC 8615)"


@@ 373,4 373,4 @@ remote = https://git.example.net/foo/bar-site.git
remote = https://lab.example.org/foo-mirror/bar-site.git
```

Since the same values of `site.<ID>.remote` may also appear in a site's configuration file, a site author may make `<SITE-ROOT>/.well-known/gwit.ini` a relative symbolic link to the former to avoid duplicating information among both files.
Since the same values of `site.<ID>.remote` may also appear in a site's configuration file `_gwit/self.ini`, a site author may make `<SITE-ROOT>/.well-known/gwit.ini` a relative symbolic link to the former to avoid duplicating information among both files.