rasl.src.html

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>RASL — Retrieval of Arbitrary Structures & Links</title>
  </head>
  <body>
    <div id="abstract">
      <p>
        RASL is a URL scheme used to identify content-addressed DASL resources
        along with a simple HTTP-based retrieval method.
      </p>
    </div>
    <!--
      XXX FOR FUTURE WORK
      - API for publishing & looking up over AT, with storage in repos
      - do we want hosts gossipping to one another or is AT enough?
    -->
    <section>
      <h2>Introduction</h2>
      <p>
        Content-addressed resources are "self-certifying," which is to say that
        you don't need any external authority to certify that the content you
        have when you resolve the identifier is correct: because the identifier
        contains a hash, you can (and should) verify that you obtained the right
        content yourself ([[ipfs-principles]]). The identifier is enough to
        certify the content. This has several implications, but two are
        particularly relevant for this specification:
      </p>
      <ul>
        <li>
          When resolving a content-addressed identifier, you can obtain the content
          from anyone. It doesn't have to be the content's author. You can even
          obtain it from entirely untrusted sources — given that you can always
          certify it, you don't need to trust whoever gives it to you. As a result,
          the authority part of a URL — the part that can certify the content you
          get, which is the domain part in an <code>https</code> URL — is the
          CID itself ([[cid]]).
        </li>
        <li>
          Because it doesn't matter where you get content from, content-addressed
          URLs are inherently transport-independent. There are benefits to agreeing
          on transport (if only so that people can find one another's content)
          but as a client, if you know of several potential ways of obtaining a
          CID you are free to use whichever you prefer or to try several in
          whatever order.
        </li>
      </ul>
      <p>
        Taking these aspects into consideration, this specification defines a URL
        scheme in which the CID is the authority, along with optional hints of
        potential look-up locations, and defines a retrieval method but does not
        mandate that RASL retrieval rely on it.
      </p>
      <section>
        <h2>The <code>rasl</code> URL Scheme</h2>
        <p>
          RASL URLs look like this:
          <code>rasl://bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4/?hint=berjon.com&hint=bsky.app</code>.
          This breaks down into the following components:
        </p>
        <ul>
          <li>
            The <code>rasl</code> scheme. This is simply used as an entry point into RASL semantics.
          </li>
          <li>
            An authority, which is simply a DASL CID ([[cid]]), here <code>bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4</code>.
          </li>
          <li>
            A path (here just <code>/</code>) that is empty or <code>/</code> and that is expected
            to be ignored since RASL is only used for raw data retrieval.
          </li>
          <li>
            A query string part, that is parsed according to CGI rules and that contains
            zero or more <code>hint</code> entries, each of which is a host from which
            that CID can be obtained.
          </li>
        </ul>
        <p>
          Use the following steps to <dfn>parse a RASL URL</dfn>:
        </p>
        <ol>
          <li>Accept a string <var>url</var> and parse it according to the <a href="https://url.spec.whatwg.org/#url-parsing">URL Standard</a> ([[url]]).</li>
          <li>If that's a failure, return the failure.</li>
          <li>Read the <code>host</code> part of the parsed URL and store that in <var>cid</var>.</li>
          <li>If <var>cid</var> is not a valid CID ([[cid]]), return failure.</li>
          <li>
            Select all the tuples in the query object associated with the URL ([[url]]) whose name is
            exactly <code>hint</code>. Each value must match the syntax of a valid host for the
            <code>https</code> scheme and values which do not match this syntax must be ignored
            and removed from this list. Store the remaining values in <var>hints</var>. If there were none
            then <var>hints</var> is an empty array.
          </li>
          <li>Return the URL's parts as well as <var>cid</var> and <var>hints</var>.</li>
        </ol>
      </section>
      <section>
        <h2>Fetching RASL</h2>
        <p>
          A user agent may retrieve a CID in whichever way it prefers. This section
          provides a simple standard for HTTP-based CID retrieval, to make it
          easy for authors to publish content to their own sites and have it
          retrieved, without having to worry about operating any infrastructure
          beyond the web server they already have.
        </p>
        <p>
          Use the following steps to <dfn>fetch a RASL URL</dfn>:
        </p>
        <ol>
          <li>Accept a string <var>url</var> and parse it according to the steps to <a>parse a RASL URL</a>.</li>
          <li>
            Construct a <var>request</var> using <var>cid</var> from the <var>url</var> as well as <var>hints</var> that may
            be from the URL or from elsewhere (this is entirely up to you):
            <ol>
              <li>
                For each hint, construct a request URL that is the concatenation of <code>https://</code>,
                the hint as host, <code>/.well-known/rasl/</code>, and the <var>cid</var>.
              </li>
              <li>
                Prepare the request such that it has a method of either <code>GET</code> or <code>HEAD</code>,
                that it is stateless (no cookies, no credentials of any kind), and that it uses no content
                negotiation.
              </li>
            </ol>
          </li>
          <li>
            Fetch the <var>request</var>s. How these get prioritised is entirely up to the implementation. It
            is common to run them all in parallel and abort them with the first success response.
            Note that the <code>.well-known</code> path may redirect, so be ready to handle that.
            This makes it possible to create sites that are published the usual way and to have a RASL that
            is simply a redirect to the resource. So for instance, you may have an existing
            <code>https://berjon.com/kitten.jpg</code> the CID for which is
            <code>bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4</code>.
            This can be published as this RASL URL:
            <code>rasl://bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4/?hint=berjon.com</code>.
            A client can retrieve it by constructing a request to this URL:
            <code>https://berjon.com/.well-known/rasl/bafkreifn5yxi7nkftsn46b6x26grda57ict7md2xuvfbsgkiahe2e7vnq4</code>.
            In turn, the latter may simply return a 307 redirect back to <code>https://berjon.com/kitten.jpg</code>.
            (Yes, this is HTTP with extra steps, but the extra steps get you self-certifying content.)
          </li>
          <li>
            If the response is a redirect but not a 307, the client should treat it as if it
            had been a 307 anyway.
          </li>
          <li>
            If none of the responses are successful, return failure.
          </li>
          <li>
            Set the response's media type to <code>application/octet-stream</code>. (The server should have
            done that already, but may not have done so, notably if it relied on a redirect.) The purpose
            of RASL is to retrieve data in ways that are independent of the server — any media type
            processing must therefore take place at another layer. Without this, we lose the self-certifying
            nature of the system. (Note that servers are encouraged to enforce that so as not to have their
            RASL endpoints used for general-purpose web serving, which can be a security vector depending on
            where the data being served came from.)
          </li>
          <li>
            Produce a CID for the retrieved data. If that CID does not match the requested <var>cid</var>,
            return failure.
          </li>
          <li>
            Return the data.
          </li>
        </ol>
      </section>
    </section>
    <section>
      <h2>RASL Pathing</h2>
      <p>
        Implementations should ignore paths in RASL URLs. They may be used in a future
        iteration of this specification.
      </p>
    </section>
  </body>
</html>