From c68abd271cce537ced900193e59a7d5373c1bf83 Mon Sep 17 00:00:00 2001 From: Alessio Vanni Date: Sun, 16 May 2021 23:07:03 +0200 Subject: [FCFSD] document it in the handbook --- doc/handbook/chapters/developer.texi | 134 +++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/doc/handbook/chapters/developer.texi b/doc/handbook/chapters/developer.texi index 24981c020..f8eebbb58 100644 --- a/doc/handbook/chapters/developer.texi +++ b/doc/handbook/chapters/developer.texi @@ -8224,6 +8224,7 @@ record types. * Hijacking the DNS-Traffic using gnunet-service-dns:: @c * Serving DNS lookups via GNS on W32:: * Importing DNS Zones into GNS:: +* Registering names using the FCFS daemon:: @end menu @node libgnunetgns @@ -8736,6 +8737,139 @@ single threaded implementation and inefficient, sequential calls of gnunet-namestore. In the future a solution that uses the C API would be cleaner and better. +@node Registering names using the FCFS daemon +@subsection Registering names using the FCFS daemon + +This section describes FCFSD, a daemon used to associate names with PKEY +records following a ``First Come, First Served'' policy. This policy means +that a certain name can not be registered again if someone registered it +already. + +The daemon can be started by using @code{gnunet-namestore-fcfsd}, which will +start a simple HTTP server on localhost, using a port specified by the +@code{HTTPORT} value in its configuration. + +Communication is performed by sending GET or POST requests to specific paths +(``endpoints''), as described in the following sections. + +The daemon will always respond with data structured using the JSON format. +The fields to be expected will be listed for each endpoint. + +The only exceptions are for the ``root'' endpoint (i.e. @code{/}) which will +return a HTML document, and two other HTML documents which will be served when +certain errors are encountered, like when requesting an unknown endpoint. + +@menu +* Obtaining informations from the daemon:: +* Submitting data to the daemon:: +* Customizing the HTML output:: +@end menu + +@cindex FCFSD GET requests +@node Obtaining informations from the daemon +@subsubsection Obtaining informations from the daemon + +To query the daemon, a GET request must be sent to these endpoints, placing +parameters in the address as per the HTTP specification, like so: + +@example +GET /endpoint?param1=value¶m2=value +@end example + +Each endpoint will be described using its name (@code{/endpoint} in the +example above), followed by the name of each parameter (like @code{param1} and +@code{param2}.) + +@deffn Endpoint /search name +This endpoint is used to query about the state of @var{name}, that is, whether +it is available for registration or not. + +The response JSON will contain two fields: + +@itemize @bullet +@item error +@item free +@end itemize + +@code{error} can be either the string @code{"true"} or the string +@code{"false"}: when @code{"true"}, it means there was an error within the +daemon and the name could not be searched at all. + +@code{free} can be either the string @code{"true"} or the string +@code{"false"}: when @code{"true"}, the requested name can be registered. +@end deffn + +@cindex FCFSD POST requests +@node Submitting data to the daemon +@subsubsection Submitting data to the daemon + +To send data to the daemon, a POST request must be sent to these endpoints, +placing the data to submit in the body of the request, structured using the +JSON format, like so: + +@example +POST /endpoint +Content-Type: application/json +... + +@{"param1": value1, "param2": value2, ...@} +@end example + +Each endpoint will be described using its name (@code{/endpoint} in the +example above), followed by the name of each JSON field (like @code{param1} +and @code{param2}.) + +@deffn Endpoint /register name key +This endpoint is used to register a new association between @var{name} and +@var{key}. + +For this operation to succeed, both @var{NAME} and @var{KEY} @strong{must not} +be registered already. + +The response JSON will contain two fields: + +@itemize @bullet +@item error +@item message +@end itemize + +@code{error} can be either the string @code{"true"} or the string +@code{"false"}: when @code{"true"}, it means the name could not be registered. +Clients can get the reason of the failure from the HTTP response code or from +the @code{message} field. + +@code{message} is a string which can be used by clients to let users know the +result of the operation. It might be localized to the daemon operator's +locale. +@end deffn + +@node Customizing the HTML output +@subsubsection Customizing the HTML output + +In some situations, the daemon will serve HTML documents instead of JSON +values. It is possible to configure the daemon to serve custom documents +instead of the ones provided with GNUnet, by setting the @code{HTMLDIR} value +in its configuration to a directory path. + +Within the provided path, the daemon will search for these three files: + +@itemize @bullet +@item fcfsd-index.html +@item fcfsd-notfound.html +@item fcfsd-forbidden.html +@end itemize + +The @file{fcfsd-index.html} file is the daemon's ``homepage'': operators might +want to provide informations about the service here, or provide a form with +which it is possible to register a name. + +The @file{fcfsd-notfound.html} file is used primarily to let users know they +tried to access an unknown endpoint. + +The @file{fcfsd-forbidden.html} file is served to users when they try to +access an endpoint they should not access. For example, sending an invalid +request might result in this page being served. + @cindex GNS Namecache @node GNS Namecache @section GNS Namecache -- cgit v1.2.3