path: root/doc/disfluid.texi

\input texinfo
@c -*-texinfo-*-

@c %**start of header
@setfilename disfluid.info
@documentencoding UTF-8
@settitle Demanding Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid
@c %**end of header

@set UPDATED 02 April 2023
@set UPDATED-MONTH April 2023
@include version_number.texi

@copying
Copyright @copyright{} 2023 Vivien Kraus

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end quotation
@end copying

@dircategory The Algorithmic Language Scheme
@direntry
* Disfluid: (disfluid)Decentralized Authentication on the Web
@end direntry

@titlepage
@title Interoperability to Strengthen the Free (Libre) Web: Introducing Disfluid
@author Vivien Kraus

@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*

@insertcopying
@end titlepage

@contents

@c *********************************************************************
@node Top
@top Disfluid

Disfluid is an independent implementation of a web stack focusing on
interoperability. In this implementation, the users control what
programs run in their computers. They also choose who to trust for
online data storage and processing, without needing any permission, or
can self-host their data.

The software is available at
@url{https://labo.planete-kraus.eu/disfluid.git}.

@menu
* Decentralized Authentication on the Web:: What is Disfluid?
* Running disfluid::
* The Disfluid Cache::
@end menu

@c *********************************************************************

@node Decentralized Authentication on the Web
@chapter Decentralized Authentication on the Web

Authentication on the web is currently handled in the following way:
anyone can install a server that will authenticate users on the
web. The problem is interoperability. If a client (an application)
wants to authenticate a user, it has to be approved by the
authentication server. In other words, if @var{useful-program} wants
to authenticate @var{MegaCorp} users, then @var{useful-program} has to
register to @var{MegaCorp} first, and get approved. This goes against
the principle of permission-less innovation, which is at the heart of
the web.

In the decentralized authentication web, the most successful attempt
so far is that of ActivityPub. All servers are interoperable with
respect to authentication: if user A emits an activity, it is
forwarded by A's server to its recipients, and A's server is
responsible for A's identity.

Another approach is that of Solid. While ActivityPub feels like
extensible e-mail over the (semantic) web, Solid aims to specify
everything, including what ActivityPub would call client-to-server, so
that the client applications can truly be decoupled from the
servers. Also Solid aims to have finer-grained interoperable
permissions and authorizations, and wants to integrate a full Linked
Data Platform, so that documents can be published directly on the
server instead of exchanged from server to server. Another feature of
Solid is to be fully usable from within the sandbox of a web browser,
which complicates the requirements.

Keeping all of this in mind, Disfluid wants to be a practical way to
enjoy the social network in an interoperable manner, where people
control the software they use.

@node Running disfluid
@chapter Running disfluid

@image{disfluid-main-window, 15cm}

Disfluid is packaged for the GNOME desktop as the Experiences
application. Experiences provides a main menu on the top right of the
screen.

@node The Disfluid Cache
@chapter The Disfluid Cache

@cindex cache
@cindex cache entry
Disfluid caches frequently-used data, to avoid overloading the
network. Each response and associated request are considered for cache
storage. They constitute a @dfn{cache entry}.

@cindex cache key
Each cache entry file stores some metadata, a @dfn{cache key}, the
response, and response body. To query the cache for an entry, the
@dfn{primary key} combines the HTTP method and effective URI. When the
response varies depending on a combination of headers, the values of
the relevant request headers are also considered as a @dfn{secondary
key}.

For instance, suppose that the following HTTP 1.1 request made over
https:
@example
GET /example HTTP/1.1
Host: example.com
Accept: text/plain
Foo: bar
Foo: other,thing
If-None-Match: W/"hello", "world"
If-None-Match: W/"hi :)"

@end example

has the following HTTP 1.1 response:

@example
HTTP/1.1 200 Hi
Content-Type: text/plain
ETag: W/\"hello\"
Vary: accept, foo
Vary: accept

Hi :)
@end example

Then the @dfn{cache key} is composed as:

@example
GET https://example.com/example
text/plain
bar,other,thing
text/plain
@end example

The first line of the cache key is the primary key. When querying the
cache, you should know the value. There may be different responses
that share the same primary key. You then have to examine the stored
response, and compose the list of varied header values, in order, to
narrow down the list of possible stored responses. Notice that you
must respect the order and multiplicity of all varied headers, and you
must aggregate all the values for duplicated request headers.

If the response has a Vary header for a request header that is not set
in the request, then the cache key has an empty corresponding line.

@deftypefun int disfluid_compute_cache_key (const char *@var{request_scheme}, const char *@var{request_header}, const char *@var{response_header}, size_t @var{max_key}, char *@var{key})
Write the cache key to @var{key}, up to @var{max_key}. The result is
NUL-terminated.

Return:

@table @strong
@item 0
on success;
@item -1
if the key cannot be computed due to an HTTP/1.1 error in the arguments;
@item -2
if the allocated @var{key} is too small to contain the whole key plus
a final NUL character.
@end table

@var{request_scheme}, @var{request_header}, @var{response_header} and
@var{key} must be non-overlapping.
@end deftypefun

@cindex cache entry metadata
Disfluid also store some metadata in the cache entry: the request and
response dates, according to the client, a boolean flag to mark an
entry as invalidated, and the HTTP scheme that was used (HTTP or
HTTPS).

@cindex hash, cache entry hash
If you have a method and URI to query, you can find all the relevant
entries by hashing the request method and URI.

@cindex private cache
When querying the cache for a @strong{private} cache implementation,
you must make sure to only consider entries that are available to the
party that is querying the cache. The method and URI are salted with
an optional password. If the password is not the empty string, then
only cache entries that have been added specifically with that
password will be available. If you are running a multi-user cache, you
can query the cache with the user name as the password in a private
setting, and then query the cache again with an empty password in a
shared setting, so you get all the private entries for that user, plus
all the shared entries.

@deftypefun int disfluid_hash_primary_cache_key (const char *@var{method}, const char *@var{uri}, const char *@var{password}, size_t @var{password_length}, size_t @var{max_hash}, char *@var{hash})
Hash @var{method} and @var{uri} to get a NUL-terminated hexadecimal
string of characters in @var{hash}. At most @var{max_hash} bytes will
be written. If @var{max_hash} is too short, then @var{hash} may not be
NUL-terminated, and the value @code{-2} is returned. Otherwise,
@code{0} is returned.
@end deftypefun

@bye