~ivilata/gwit-spec

2bc706e77db3657f04b24b68d374c9370b663533 — Ivan Vilata-i-Balaguer 4 months ago 5026172 
Split introductions out of the site configuration file.

This breaking change tries to avoid INI files which may grow too big.  It also
makes site configurations and site introductions use the same format.
However, it introduces somewhat author-unfriendly file names.

Close the associated issue `split-ini-file-into-self-and-introductions`.
patch browse .tar.gz 
2 files changed, 31 insertions(+), 14 deletions(-)

M README.md
M issues/split-ini-file-into-self-and-introductions.gmi

M README.md => README.md +21 -14
@@ 105,25 105,15 @@ The `site.<SITE-ID>` section of `_gwit/self.ini` contains some basic information
- `root` (single, optional): A directory in the repository to be used as the site's **root directory** instead of, and relative to, its top directory. If missing, it defaults to that top directory. It MUST consist of one or more non-empty path components separated by a single forward slash (`/`). It MUST NOT contain `.` or `..` path components. Convenient when using a static site generator that writes its output to a directory. Example (for a site containing Gemini files): `output`.
- `index` (single, optional): The name of the **index file**. It MUST NOT be empty, `.` or `..`, or contain slash characters (`/`). When a gwit client is told to retrieve a directory, and it contains a file named as the index file, the contents of the file SHOULD be produced instead of a directory listing. Example (for a site containing Gemini files): `index.gmi`.
- `remote` (multiple, recommended): A location recommended by the author for retrieving the site, the URL of a Git remote. Multiple such locations may be given (for increased availability), each as a different `remote` value, which a client MAY consider in order of appearance. Example: `https://git.example.net/foo/bar-site.git`.
- `branch` (single, optional): If given, the name of the Git branch to be used as the default branch for the site. This is useful when the given branch of the Git repository contains files output by a static site generator, while `remote`'s default branch (usually `master` or `main`) only contains sources. It takes precedence over other values of `meet.branch` for this site (see further below). Example (for a site converted to Gemini files): `gemini-output`.
- `branch` (single, optional): If given, the name of the Git branch to be used as the default branch for the site. This is useful when the given branch of the Git repository contains files output by a static site generator, while `remote`'s default branch (usually `master` or `main`) only contains sources. It takes precedence over the values from introductions to this site (see further below). Example (for a site converted to Gemini files): `gemini-output`.
- `alt` (multiple, optional): If given, the prefix for this site's URIs in a publication system other than gwit. The gwit client MAY interpret links in this site using those prefixes as if they began with a single slash (`/`) instead of the prefix and subsequent slashes. This enables reusing site contents in gwit without needing to adapt local absolute links. Multiple such prefixes may be given, each as a different `alt` value. Example: `https://foo.example.net/bar/` enables rewriting `https://foo.example.net/bar//page.html` to `/page.html`.

`meet.<INTRO-SITE-ID>` sections constitute **site introductions**, which allow the site author to provide the information needed for the initial retrieval of other gwit sites (see further below). *This is the main means of content discovery in gwit*, thus site authors SHOULD provide such introductions for the sites that they link to. The section's `<INTRO-SITE-ID>` MUST be the identifier of the introduced site, with the same format as the `site.<SITE-ID>` section (see above). Example: `[meet "0x0123456789abcdef0123456789abcdeffedcba98"]`. Values recognized in the section are:

- `name` (single, recommended): A short name or handle for the introduced site. Example: `Someone's site`.

  A gwit client MAY regard it as the author's proposed name for that site (its edge name); as such, the client SHOULD allow configuring a petname value that overrides it along other proposed names for the site.
- `remote` (multiple, mandatory): The URL of a Git remote from where the introduced site can be retrieved. Example: `https://hub.example.com/someone/my-gwit-site.git`.
- `branch` (single, optional): The branch of the Git repository to be used as the default branch for the introduced site. Example: `published`.

These values have the same number, format and restrictions as their homonyms in the `site.<SITE-ID>` section.

The scope of the different site configuration values is described below:

- `site.name`: The value in the latest site version, if defined, SHOULD be read on initial site retrieval, then applied to all versions of the site (past and future, until manually overridden).
- `site.title(-*)`, `site.desc(-*)`: The value in the latest site version, if defined, MAY be applied to previous versions as well, though the value in a specific version, if defined, SHOULD be applied to that version.
- `site.license`, `site.root`, `site.index`, `site.alt`: The value in a specific version, if defined, SHOULD be applied only to that version.
- `site.remote`, `site.branch`, `meet.*`: The value in the latest site version, if defined, MAY be applied on initial site retrieval and updates. The handling of old values is at the discretion of the gwit client.
- `site.remote`, `site.branch`: The value in the latest site version, if defined, MAY be applied on initial site retrieval and updates. The handling of old values is at the discretion of the gwit client.

This is a sample `_gwit/self.ini` file using all sections and values:



@@ 144,9 134,26 @@ branch = gemini-output
alt = https://example.net/~foo/bar/
alt = https://foo.example.net/bar/
alt = gemini://foo.example.net/bar-site/
```

### Site introductions

A site's `_gwit` directory may also contain **site introductions**, which allow the site author to provide the information needed for the retrieval of other gwit sites. *This is the main means of content discovery in gwit*, thus site authors SHOULD provide such introductions for the sites that they link to.

[meet "0x0123456789abcdef0123456789abcdeffedcba98"]
An introduction for a given site MUST be contained in the file `_gwit/<SITE-ID>.ini`, where `<SITE-ID>` is the identifier of the introduced site, encoded as `0x` plus the lower case hexadecimal digits of the full fingerprint of the PGP site key. Example: `_gwit/0x0123456789abcdef0123456789abcdeffedcba98.ini`.

The format of a site introduction is that of a site configuration file (see further above), with the exception that `site.remote` becomes a mandatory value. For any given introduction, its `<SITE-ID>` MUST match between the file name `_gwit/<SITE-ID>.ini` and its section `[site "<SITE-ID>"]`.

While the values of `site.remote` and `site.branch` may be used for retrieving the introduced site, the rest of values may be considered as mere hints (since there is no guarantee that they come from that site's author), and they SHOULD be overridden by the client with the equivalent values of the actual site configuration file, once available locally.

Also note that a gwit client MAY regard an introduction's `site.name` as this site author's proposed name for that site (its edge name); as such, the client SHOULD allow configuring a petname value that overrides it along other proposed names for the site.

This is a sample introduction, stored in the `_gwit/0x0123456789abcdef0123456789abcdeffedcba98.ini` file:

```
[site "0x0123456789abcdef0123456789abcdeffedcba98"]
name = Someone's site
desc = The site that Someone published while studying at the University.
remote = https://hub.example.com/someone/my-gwit-site.git
remote = https://lab.example.org/s.one/gwit-site.git
branch = published


@@ 279,7 286,7 @@ A client MAY display a petname-decorated version of a gwit URI. Such representat

As mentioned further above, a gwit client may learn the self-proposed name of a site from its configuration file, as well as the edge names of introduced sites. In that case, it should also allow to set a different petname for any such site.

For instance, Alice retrieves Bob's site (with ID `<BOB-ID>`) for the first time using her gwit client. That site's `_gwit/self.ini` file sets `Bob's site` as the value of `site.name`; it also introduces Carol's site (with ID `<CAROL-ID>`) using the section `[meet "<CAROL-ID>"]` with `name = This is Carol`.
For instance, Alice retrieves Bob's site (with ID `<BOB-ID>`) for the first time using her gwit client. That site's `_gwit/self.ini` file sets `Bob's site` as the value of `site.name`; the site also contains an introduction of Carol's site (with ID `<CAROL-ID>`) having `This is Carol` as the value of `site.name`.

Alice's gwit client follows the petname implementation hints described in the paper [Implementation of a petnames system in an existing chat application][petnames-impl]. Thus, when the client finds a link to



M issues/split-ini-file-into-self-and-introductions.gmi => issues/split-ini-file-into-self-and-introductions.gmi +10 -0
@@ 7,3 7,13 @@ The "gwit.ini" site configuration file currently contains both the configuration
Introductions should be splitted out of "gwit.ini". However, if they are all put in a single file, it would also have the aforementioned size issues itself.

One approach would be to have each introduction in its own file. Since there may be many such files, they should be moved into a common directory. The naming of these files should be considered (easy to create for author, easy to locate for client), along with the potential issues on having thousands of such files in a Git directory (e.g. for an indexing or directory site).

## Resolution

After "gwit.ini" was moved to "_gwit/self.ini", and "site" and "meet" sections got site IDs as unique subsection names, the "meet" section for "<INTRO-SITE-ID>" has been moved to "_gwit/<INTRO-SITE-ID>.ini". As a result, the site configuration file can now remain small. Also, the introduction is easy to find by a client (given the target site ID). However, getting the file name right for a non-tech savvy author may be tricky (external tools may help); an alternative like using a short PGP ID would introduce new concepts.

Site introductions have been defined to have the same format and values as site configurations (the "meet" section has been renamed to "site"), which means that the site author may just include the target site's configuration file as an introduction, and values beside remotes and branch are just considered as hints. The author may alter or remove them at their discretion, but at least one remote URL must be provided for the introduction to be valid.

Besides the somewhat author-unfriendly introduction file name format, another open issue is that no special provisions are made for sites with a very large number of introductions. Splitting the file name like "_gwit/0x0123/456789abcdef0123456789abcdeffedcba98.ini" to reduce the directory size would make it even more cumbersome to handle. Since more than 100K site introduction entries can fit in an 8MiB (uncompressed) Git tree, it is probably better to avoid more sophisticated solutions for the moment.

* closed