Re: [Uri-review] Review request for gittorrent: URI scheme

["Roy T. Fielding" <[e-mail]>]

> On Apr 5, 2016, at 9:41 PM, Chris Rebert <[e-mail]> wrote:
> 
> On Sun, Apr 3, 2016, at 08:10 PM, Chris Rebert wrote:
>> Hello,
>> 
>> Per the advice of RFC 7595, I hereby present the following proposed
>> registration of the "gittorrent" provisional URI scheme for review.
>> Any feedback is greatly appreciated. Thanks.
> 
> Here's a revised draft based on the feedback thus far.
> 
> Cheers,
> Chris
> ****
> http://chrisrebert.com
> Browser 🐛 of the day:
> https://developer.microsoft.com/en-us/microsoft-edge/platform/issues/7124038/
> 
> ********
> 
> Scheme name:  gittorrent
> 
> Status:  Provisional
> 
> Applications/protocols that use this scheme name:
>  GitTorrent ("A decentralization of GitHub using BitTorrent and
>  Bitcoin")
> 
> Contact:
>  Scheme creator:
>    Chris Ball <http://printf.net/>
>  Registering party:
>    Chris Rebert <[e-mail]>
> 
> Change controller:
>  Either the scheme creator or the registering party.
> 
> References:
>  Ball, C., "Announcing GitTorrent: A Decentralized GitHub", 29 May
>  2015,
>      <http://blog.printf.net/articles/2015/05/29/announcing-gittorrent-a-decentralized-github/>.
>  Ball, C., "GitTorrent", 2016, <http://gittorrent.org/>.
>  Ball, C., "GitTorrent", 2016, <https://github.com/cjb/GitTorrent>.
>  Bernstein, D. J., Duif, N., Lange, T., Schwabe, P., and B. Yang,
>      "Ed25519: high-speed high-security signatures", 27 September 2011,
>      <https://ed25519.cr.yp.to/>.
>  Bitcoin Project, "Bitcoin - Open source P2P money", 2016,
>      <https://bitcoin.org/en/>.
>  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange
>      Format", RFC 7159, March 2014.
>  Cohen, B., "BEP 3: The BitTorrent Protocol Specification", 11 October
>  2013,
>      <http://www.bittorrent.org/beps/bep_0003.html>.
>  Eastlake 3rd, D. and P. Jones, "US Secure Hash Algorithm 1 (SHA1)",
>  RFC 3174,
>      September 2001.
>  "Git", 2016, <https://git-scm.com/>.
> 
> Scheme syntax:
>  This scheme uses a profile of the RFC 3986 generic URI syntax.
> 
>  At the time of writing this registration, a gittorrent URI comes in
>  one of
>  three forms:
> 
>    0. Where the "authority" component is a domain name
>      Example:  gittorrent://github.com/cjb/recursers
>      The "path" and "query" components have no extra restrictions.
> 
>    1. Where the "authority" component is a 40-byte hexadecimal number
>    (the
>       conventional representation of a SHA-1 hash digest)
>      Example: 
>      gittorrent://81e24205d4bac8496d3e13282c90ead5045f09ea/recursers
>      In this case, the "query" component is not permitted, and
>      the "path" component consists of exactly one segment (the Git
>      repository
>      name).
> 
>    2. Where the "authority" is a username
>      Example:  gittorrent://cjb/foo
>      In this case, the "query" component is not permitted, and
>      the "path" component consists of exactly one segment (the Git
>      repository
>      name).
> 
>  There may be further restrictions on the format of usernames and
>  repository
>  names.
> 
>  Given the youth of the GitTorrent project, additional gittorrent: URI
>  forms
>  might be defined in the future, and the interpretation of the existing
>  forms
>  could potentially be changed.  Implementors SHOULD consult the
>  GitTorrent
>  project for the most up-to-date information on gittorrent: URIs, as
>  there is
>  currently no de jure standard for them.  This third-party URI scheme
>  registration is based on the GitTorrent reference implementation's
>  documentation at the time of writing.
> 
> Scheme semantics:
>  gittorrent URIs represent Git repositories and specify the metadata
>  necessary
>  to clone a repository, to read the repository's commits, and, with the
>  necessary cryptographic key, to write commits to the repository.
> 
>  See the GitTorrent project for full details.
>  The following is a summary of read-only usage when cloning the
>  repository:
> 
>  In URIs of type (0), the SHA-1 hash identifier of the latest commit of
>  the
>  primary branch is fetched via the git protocol, as if this had been a
>  git:
>  URI.  The actual data for that commit (and its ancestors, if
>  necessary) is
>  then downloaded via BitTorrent.

I think that is unnecessary and confusing.  Just use the git URI for identification
of this resource and something else (markup, configuration, command-line, ... another URI)
to indicate that BitTorrent is the protocol used to retrieve it.  This is no different
from the various schemes that can be proxied over HTTP by defining environment variables
or other config properties.

>  In URIs of type (1), the SHA-1 hash in the "authority" component is
>  used as a
>  key for a lookup in a BitTorrent DHT (distributed hash table).  The
>  value
>  obtained from the lookup is a JSON object representing a GitTorrent
>  user
>  profile, which includes the names of that user's repositories, the
>  names of
>  those repositories' git refs, and the SHA-1 hash identifiers of the
>  commits
>  that those refs currently point to.  The "path" component is the name
>  of the
>  repository, and is used to look up the corresponding SHA-1 hash commit
>  identifier of the primary branch of the repository in the user
>  profile.  The
>  actual data for that commit (and its ancestors, if necessary) is then
>  downloaded via BitTorrent.

The authority component is for identification of name-based authorities,
as in (0).  Using it two different ways for the same scheme would be a
very bad idea. Likewise, restricting the path to one name means it isn't
hierarchical, so there is no reason for it to be a path.  Just use

    gittorrent:81e24205d4bac8496d3e13282c90ead5045f09ea?recursers

to be distinct from other URI forms, or see below for a single format.

>  In URIs of type (2), the username in the "authority" component is used
>  for an
>  OP_RETURN transaction lookup in Bitcoin's blockchain.  If successful,
>  this
>  lookup yields a SHA-1 hash which is then used as a key for a lookup in
>  a
>  BitTorrent DHT (distributed hash table).  The value obtained from the
>  lookup
>  is a JSON object representing a GitTorrent user profile (as described
>  in the
>  previous paragraph).  The "path" component is the name of the
>  repository, and
>  is used to look up the corresponding SHA-1 hash commit identifier for
>  the
>  primary branch of the repository in the user profile.  The actual data
>  for
>  that commit (and its ancestors, if necessary) is then downloaded via
>  BitTorrent.

There is no need for this to be a separate type of URI.  Just do

    gittorrent:cjb?foo

and it is type (1) with a mechanical distinction (usernames are not hashes).

Alternatively, you can merge all three forms into a singular format that
is consistent with the generic URI syntax, as in

    "gittorrent:" [ "//" [ username "@" ] [ authority ] ] path [ "?" sha1 ]

and just exclude the parts that aren't needed for a given identifier.
 

Note that the above are just comments based on the registration.  IMO, the
system reflects a misunderstanding of how URIs ought to be used as identifiers,
and how representations (or redirections, if available) ought to refer to
other resources.  IOW, what you really should have is a media type definition
of the "JSON object representing a GitTorrent user profile" and then define various
ways of accessing such a representation in the form of schemes for torrent,
http(s), blockchain, etc.  In that case, a fragment can be used for the types
of indirection used above.

....Roy