229 lines
14 KiB
Markdown
229 lines
14 KiB
Markdown
# Glossary
|
|
|
|
This page collects one unambiguous name for each concept discussed in [federation.md](federation.md)
|
|
and the [design-in-progress](design-in-progress/) documents, so later writing can refer to them
|
|
consistently instead of reinventing or subtly renaming them. Entries are grouped by topic, and
|
|
alphabetical within each group. Each one notes whether the concept exists in Toolshed today or is
|
|
still a design proposal, and links back to where it's discussed in full.
|
|
|
|
Two terms are easy to conflate and worth telling apart up front: a **domain** is who a handle
|
|
belongs to; an **origin** is where a classification entry came from. They look similar in prose but
|
|
are unrelated concepts, see their entries below.
|
|
|
|
---
|
|
|
|
## Federation Basics
|
|
|
|
**Backend** (Implemented)
|
|
The server software that stores an [actor](#actor)'s data and is currently authoritative for a
|
|
[domain](#domain). Deliberately decoupled from both the domain (a backend isn't tied to one domain,
|
|
and can be authoritative for many at once) and the [frontend](#frontend) (the app a user loads isn't
|
|
necessarily served by the backend that ends up handling their requests). Prefer "backend" over the
|
|
looser word "server" when precision matters, "server" is used informally in places to mean either
|
|
backend or domain interchangeably.
|
|
*See: [federation.md](federation.md#servers)*
|
|
|
|
**Discovery** (Implemented)
|
|
The lookup a [frontend](#frontend) performs to find which [backend](#backend) is currently
|
|
authoritative for a [domain](#domain), given a [handle](#handle). Operational/DNS-level detail
|
|
about how this lookup works belongs in the deployment docs, not here, this glossary only fixes the
|
|
name for the concept.
|
|
*See: [federation.md](federation.md#servers)*
|
|
|
|
**Domain** (Implemented)
|
|
The half of a [handle](#handle) after the `@`, e.g. `toolsheddomain.tld`. An authority record, not
|
|
a location or a piece of software: it says which [backend](#backend) currently vouches for handles
|
|
under it, nothing more. Not the same thing as an [origin](#origin), see the note at the top of this
|
|
page.
|
|
*See: [federation.md](federation.md#servers)*
|
|
|
|
**Frontend** (Implemented)
|
|
The client application a user interacts with. Independent of any one [domain](#domain) or
|
|
[backend](#backend): given a handle, it performs [discovery](#discovery) to find the right backend
|
|
and talks to it directly, regardless of where the frontend itself was loaded from.
|
|
*See: [federation.md](federation.md#servers)*
|
|
|
|
**Handle** (Implemented)
|
|
A name that's unique within its own scope and carries, as part of itself, enough information to say
|
|
where it's authoritative, without needing a central registry to look it up. The general term
|
|
covering [user handles](#user-handle), [group handles](#group-handle) (proposed),
|
|
[classification handles](#classification-handle), and [item handles](#item-handle) (proposed).
|
|
*See: [federation.md](federation.md#unique-handles)*
|
|
|
|
**Strict resolution** (Implemented)
|
|
The rule that a reference to a [handle](#handle) a backend doesn't recognize is left unresolved
|
|
rather than guessed at or silently merged into something that looks similar. The foundational
|
|
guarantee the rest of the handle system, and most of the open problems in
|
|
[tags.md](design-in-progress/tags.md), are trying to preserve or actually make hold.
|
|
*See: [federation.md](federation.md#tags-properties-and-categories)*
|
|
|
|
## Actors, Identity & Sharing
|
|
|
|
**Actor** (Proposed)
|
|
Umbrella term for anything that can hold a handle, have friends, and own items. Today this only
|
|
means [user](#user). [Groups](#group) are a proposed second kind of actor, so that "friendship,"
|
|
"ownership," and "handle" all mean the same thing regardless of which kind of actor is involved.
|
|
*See: [groups.md](design-in-progress/groups.md#are-group-handles-different-from-user-handles-or-is-a-group-just-a-special-kind-of-user)*
|
|
|
|
**Availability policy** (Implemented)
|
|
A setting on an item (`private` / `share` / `lend` / `rent` / `sell`) controlling who besides the
|
|
owner can see it. Today the audience for any non-`private` policy is implicitly "all of the owner's
|
|
[friends](#friend-friendship)," equally, there's no way to name a narrower audience. See [targeted
|
|
sharing](#targeted-sharing) for the proposed alternative.
|
|
*See: [groups.md](design-in-progress/groups.md#interaction-with-availability-policy)*
|
|
|
|
**Friend / Friendship** (Implemented for users; proposed for groups)
|
|
A mutual, explicitly-established trust relationship between two [actors](#actor). Established by a
|
|
friend-request/accept exchange, which is also the point a [public key](#keypair-private-key-public-key)
|
|
is first trusted for that handle. Currently only exists between users; groups having friends, and
|
|
groups befriending groups, are proposed extensions of the same mechanism, not a new one.
|
|
*See: [federation.md](federation.md#cryptography), [groups.md](design-in-progress/groups.md#should-a-group-be-able-to-grant-read-access-to-non-members-group-friends)*
|
|
|
|
**Group** (Proposed)
|
|
A second kind of [actor](#actor), modeling collective ownership (a club, workshop, or company)
|
|
rather than any one person owning something. All members hold equal edit rights over what the group
|
|
owns; membership itself is the privilege, there's no separate owner/member distinction within a
|
|
group. Backed by a [membership list](#membership-list) rather than a [keypair](#keypair-private-key-public-key),
|
|
and identified by a [group handle](#group-handle).
|
|
*See: [groups.md](design-in-progress/groups.md#what-a-group-is)*
|
|
|
|
**Group handle** (Proposed)
|
|
A [group](#group)'s handle: a name and [domain](#domain) written like a [user handle](#user-handle)
|
|
but prefixed with `#`, e.g. `#groupname@toolsheddomain.tld`. The prefix keeps groups and users in
|
|
disjoint namespaces on the same domain (no squatting collision between a user and a group wanting
|
|
the same name) and lets an actor's kind be read directly off its handle, without a lookup.
|
|
*See: [federation.md](federation.md#users-and-groups), [groups.md](design-in-progress/groups.md#are-group-handles-different-from-user-handles-or-is-a-group-just-a-special-kind-of-user)*
|
|
|
|
**Identity** (Implemented)
|
|
A [user handle](#user-handle) paired with the [keypair](#keypair-private-key-public-key) that backs
|
|
it, held together as the one unit a [backend](#backend) actually trusts: not just a name, and not
|
|
just key material, but both at once. This is what gets established at registration for one's own
|
|
handle, and what gets recorded on [friend](#friend-friendship)-accept for someone else's handle.
|
|
Only [users](#user) have an identity in this sense, since a [group](#group) is deliberately backed
|
|
by a [membership list](#membership-list) instead of a keypair, there's no key half for a group
|
|
handle to pair with.
|
|
*See: [federation.md](federation.md#cryptography)*
|
|
|
|
**Keypair / Private key / Public key** (Implemented, users only)
|
|
The asymmetric keypair backing exactly one [user handle](#user-handle); together, a handle and the
|
|
keypair backing it are what's called an [identity](#identity). The private key signs requests made
|
|
as that user and never leaves their control; the public key is handed out to establish trust in the
|
|
handle (at registration, or via a [friend](#friend-friendship) exchange) and is used to verify
|
|
signatures. Only user handles carry a keypair, not groups, classification handles, or item handles.
|
|
*See: [federation.md](federation.md#cryptography)*
|
|
|
|
**Membership list** (Proposed)
|
|
The record of which [user handles](#user-handle) currently belong to a [group](#group), maintained
|
|
by whichever backend is authoritative for the group's handle. What backs a group's identity in
|
|
place of a keypair: a request "as the group" is a normal signed request from a current member, plus
|
|
a check against this list, not a request signed by some shared group key.
|
|
*See: [groups.md](design-in-progress/groups.md#does-a-group-need-its-own-keypair)*
|
|
|
|
**Signature / Signing** (Implemented)
|
|
The act of authenticating a request as genuinely coming from a specific [user
|
|
handle](#user-handle), unaltered, using that handle's private key. Establishes authenticity and
|
|
integrity only, not confidentiality (that's HTTPS's job) and not, today, protection against replay.
|
|
*See: [federation.md](federation.md#cryptography)*
|
|
|
|
**Targeted sharing** (Proposed)
|
|
Sharing an item with one specific [actor](#actor) (a particular friend, or a particular group)
|
|
instead of the current all-or-nothing [availability policy](#availability-policy) audience of every
|
|
friend equally. Flagged as a generalization useful beyond groups specifically, not a groups-only
|
|
feature.
|
|
*See: [groups.md](design-in-progress/groups.md#should-anyone-be-able-to-share-directly-with-a-specific-group-instead-of-with-my-friends-generally)*
|
|
|
|
**User** (Implemented)
|
|
The original, and currently only implemented, kind of [actor](#actor): backed by exactly one
|
|
[keypair](#keypair-private-key-public-key) and identified by a [user handle](#user-handle).
|
|
*See: [federation.md](federation.md#users-and-groups)*
|
|
|
|
**User handle** (Implemented)
|
|
A user's username paired with its [domain](#domain), written like an email address, e.g.
|
|
`user@toolsheddomain.tld`. Unique only within its domain, not across all of Toolshed. Contrast with
|
|
a [group handle](#group-handle), which is the same shape but prefixed with `#`. Paired with its
|
|
[keypair](#keypair-private-key-public-key), the two together are called an [identity](#identity).
|
|
*See: [federation.md](federation.md#users-and-groups)*
|
|
|
|
## Classification: Tags, Properties & Categories
|
|
|
|
**Alias** (Proposed)
|
|
An explicit, one-directional "supersedes"/"alias of" pointer from one [classification
|
|
handle](#classification-handle) to another, asserting they mean the same thing. Never inferred
|
|
automatically, always a deliberate act, in keeping with [strict resolution](#strict-resolution). For
|
|
a property alias specifically, also states a unit conversion (even if it's "identical unit, factor
|
|
1"); without one, the values behind the two handles aren't assumed to be comparable.
|
|
*See: [tags.md](design-in-progress/tags.md#open-design-ideas)*
|
|
|
|
**Classification handle** (Implemented)
|
|
Umbrella term for a [tag](#tag-property-category), [property](#tag-property-category), or
|
|
[category](#tag-property-category) handle, of the form `origin#type:name`, e.g.
|
|
`git:base#property:length`. Distinct from a [user handle](#user-handle) or [item
|
|
handle](#item-handle): it names a reusable classification concept, not an actor or an owned thing.
|
|
*See: [federation.md](federation.md#tags-properties-and-categories)*
|
|
|
|
**Definition fingerprint** (Partially implemented)
|
|
A hash of a classification entry's full definition, used to tell whether two [actors](#actor)
|
|
that both use the same handle actually mean the same thing. A sha256 of each `shared_data/*.json`
|
|
file is already computed and stored per import (`ImportedIdentifierSets.hash`), but it's only ever
|
|
recorded, not compared, so it doesn't yet catch a [handle collision](#handle-collision) in
|
|
practice.
|
|
*See: [tags.md](design-in-progress/tags.md#open-design-ideas)*
|
|
|
|
**Fragmentation** (Known problem)
|
|
Two different [classification handles](#classification-handle) that mean, or were intended to
|
|
mean, the same real-world concept (different origins, or a locally-invented tag versus a shared
|
|
one). The opposite failure from a [handle collision](#handle-collision): visible and merely
|
|
wasteful, rather than silent and dangerous.
|
|
*See: [tags.md](design-in-progress/tags.md#problem)*
|
|
|
|
**Handle collision** (Known problem)
|
|
Two [actors](#actor) independently ending up with the exact same [classification
|
|
handle](#classification-handle) string backing two different definitions, e.g. two servers that
|
|
each imported `git:ee2` from what has since become diverging branches. The dangerous mirror image
|
|
of [fragmentation](#fragmentation): silent, because nothing about the interaction signals that
|
|
anything's wrong, both sides just say the same string.
|
|
*See: [tags.md](design-in-progress/tags.md#worked-example-the-same-handle-meaning-two-different-things)*
|
|
|
|
**Origin** (Implemented)
|
|
The first component of a [classification handle](#classification-handle), naming where that tag,
|
|
property, or category came from, e.g. `git:base` in `git:base#property:length`. Not necessarily a
|
|
server or a domain, it can equally be a shared reference dataset (like the files in
|
|
`backend/shared_data/`) or a server's own locally-invented taxonomy. Not the same thing as a
|
|
[domain](#domain), see the note at the top of this page.
|
|
*See: [federation.md](federation.md#tags-properties-and-categories)*
|
|
|
|
**Tag / Property / Category** (Implemented)
|
|
The three kinds of classification entity an item can reference, each identified by a
|
|
[classification handle](#classification-handle). A property additionally carries unit metadata
|
|
(`unit_symbol`/`unit_name`), though property *values* on an item are plain, undeclared-type
|
|
strings today.
|
|
*See: [federation.md](federation.md#tags-properties-and-categories), [tags.md](design-in-progress/tags.md)*
|
|
|
|
## Items & Physical Labels
|
|
|
|
**Item Handle** (Proposed)
|
|
The compact identifier for a specific item that's meaningful outside its owner's own account:
|
|
`user@domain.tld:id`, the owner's [user handle](#user-handle) plus a [local id](#local-id). Used
|
|
where it's already clear from context that it's a Toolshed item, e.g. inside the app, in exports,
|
|
in logs, so it doesn't need to spell that out or be openable on its own. Contrast with [Item
|
|
URL](#item-url), the self-contained form for when no such context can be assumed.
|
|
*See: [items-labels.md](design-in-progress/items-labels.md#open-design-questions)*
|
|
|
|
**Item Label** (Proposed)
|
|
A physical, scannable encoding (QR code, barcode, or similar) of an item's [Item URL](#item-url),
|
|
meant to be printed and stuck on the physical object it refers to.
|
|
*See: [items-labels.md](design-in-progress/items-labels.md#goals)*
|
|
|
|
**Item URL** (Proposed)
|
|
The self-contained URL form of an [Item Handle](#item-handle), for use with no context at all, e.g.
|
|
an [Item Label](#item-label): `https://<any frontend>/i/user@domain.tld/id`. Has to open directly
|
|
to the right frontend and land on the right item on its own, since the reader can't be assumed to
|
|
already know what it is or which server it belongs to. Any frontend can serve this URL, the host
|
|
named in it isn't part of the item's identity, only the handle in its path is.
|
|
*See: [items-labels.md](design-in-progress/items-labels.md#open-design-questions)*
|
|
|
|
**Local id** (Implemented)
|
|
An item's identifier as it exists today: unique only within its owner's own inventory, not
|
|
meaningful outside that owner's account. The starting point both the [Item
|
|
Handle](#item-handle) and [Item URL](#item-url) build on.
|
|
*See: [federation.md](federation.md#items), [items-labels.md](design-in-progress/items-labels.md#problem)*
|