\input texinfo
@setfilename guile-fediverse.info
@documentencoding UTF-8
@settitle guile-fediverse

@include version.texi 

@copying
Copyright @copyright{} 2020 Julien Lepiller

@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

@titlepage
@end titlepage

@contents

@node Top
@top guile-fediverse

This document describes guile-fediverse version @value{VERSION}, a guile
implementation of some algorithms and specifications used in the Fediverse.

@menu
* Introduction::           What is the Fediverse?
* API Reference::          Description of the library interface.

@detailmenu
--- The Detailed Node Listing ---

API Reference

* ActivityStreams API::    Encoding and Decoding Activities.
* Webfinger API::          Finding resource locations.

@end detailmenu
@end menu

@node Introduction
@chapter Introduction

The Fediverse is a collection of applications and servers that provide a social
media platform and similar services.  They individually work as a platform,
with users (identities) and services and collectivelly form a bigger social
network, the Fedivere, by the use of different federating protocols.  Some
of them are implemented in this library.

If you are new to the concept of the Fediverse, you should try out one of the
great servers that provide service for Mastodon (the most well-known server),
Pleroma (a micro-blogging platform), Peertube (a video sharing platform), and
many more!  With one account on one of these platforms, you can interact with
any account on any of these other platforms.  Imagine commenting a Peertube
video from Mastodon and sharing it with a friend on Pleroma :)

@node API Reference
@chapter API Reference

@node ActivityStreams API
@section ActivityStreams API

TODO

@node Webfinger API
@section Webfinger API

Webfinger is a protocol that allows you to query resource location at a
well-known end-point.  The protocol is described in detail in
@uref{RFC 7033, https://tools.ietf.org/html/rfc7033}.

This library provides a small interface to use this protocol in the
@code{(webfinger webfinger)} module.

First of all, webfinger answers are in the form of a @dfn{JRD} record, meaning
JSON Resource Descriptor.  This record is encoded in the @code{<jrd-record>}
data type:

@deffn {Datatype} <jrd-record>

@table @asis
@item @code{subject}
The resource that was requested and for which the answer is given.  This is
a URI, as a string.

@item @code{aliases}
A list of zero or more URI as strings, that identify the same entity.

@item @code{properties}
A list of key-value pairs (an alist) whose keys and values are strings.  This
represents a set of properties on the subject that the webfinger server wants
to give you.

@item @code{links}
A list of links that correspond to the location of the requested identity.  These
links are objects of type @code{<link-record>}.

@end table
@end deffn

@deffn {Datatype} <link-record>

@table @asis
@item @code{rel}
A string that is either a URI or a registered relation type, as defined at
@url{http://www.iana.org/assignments/link-relations/}.

@item @code{type}
A string that represents the MIME/Type of the content accessible through the
link.

@item @code{href}
A string that represents the URI at which you can find of the requested
resource.

@item @code{titles}
An association list where keys are strings that represent a language name and
value represents the title for the content of the link in that language.

@item @code{properties}
A list of key-value pairs (an alist) whose keys and values are strings.  This
represents a set of properties on the link that the webfinger server wants
to give you.

@end table
@end deffn

The library provides two procedures to retrieve data from a webfinger server.
A low-level procedure that can query anything and a higher-level procedure to
specifically query actor objects to a Fediverse server.

@deffn {Scheme Procedure} webfinger-query @var{server} @var{resource} @
  [@var{rel}]
Queries a webfinger @var{server} for @var{resource}, which must be a URI,
represented as a string.  Returns a @code{jrd-record} object.

@end deffn

@deffn {Scheme Procedure} find-actor-object @var{user} @var{server}
Queries a webfinger @var{server} for the actor object of @@@var{user}@@@var{server}.
Note that @var{server} should be a string that represents the server name, but
has no scheme.  The procedure returns a string that corresponds to the best
link returned by the webfinger server (determined by the type when available).

This queries the resource ``acct:@var{user}@@@var{server}'' to the server.
@end deffn

@bye