aboutsummaryrefslogtreecommitdiff
path: root/doc/handbook/chapters/developer.texi
diff options
context:
space:
mode:
Diffstat (limited to 'doc/handbook/chapters/developer.texi')
-rw-r--r--doc/handbook/chapters/developer.texi134
1 files changed, 134 insertions, 0 deletions
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.
8224* Hijacking the DNS-Traffic using gnunet-service-dns:: 8224* Hijacking the DNS-Traffic using gnunet-service-dns::
8225@c * Serving DNS lookups via GNS on W32:: 8225@c * Serving DNS lookups via GNS on W32::
8226* Importing DNS Zones into GNS:: 8226* Importing DNS Zones into GNS::
8227* Registering names using the FCFS daemon::
8227@end menu 8228@end menu
8228 8229
8229@node libgnunetgns 8230@node libgnunetgns
@@ -8736,6 +8737,139 @@ single threaded implementation and inefficient, sequential calls of
8736gnunet-namestore. In the future a solution that uses the C API would be cleaner 8737gnunet-namestore. In the future a solution that uses the C API would be cleaner
8737and better. 8738and better.
8738 8739
8740@node Registering names using the FCFS daemon
8741@subsection Registering names using the FCFS daemon
8742
8743This section describes FCFSD, a daemon used to associate names with PKEY
8744records following a ``First Come, First Served'' policy. This policy means
8745that a certain name can not be registered again if someone registered it
8746already.
8747
8748The daemon can be started by using @code{gnunet-namestore-fcfsd}, which will
8749start a simple HTTP server on localhost, using a port specified by the
8750@code{HTTPORT} value in its configuration.
8751
8752Communication is performed by sending GET or POST requests to specific paths
8753(``endpoints''), as described in the following sections.
8754
8755The daemon will always respond with data structured using the JSON format.
8756The fields to be expected will be listed for each endpoint.
8757
8758The only exceptions are for the ``root'' endpoint (i.e. @code{/}) which will
8759return a HTML document, and two other HTML documents which will be served when
8760certain errors are encountered, like when requesting an unknown endpoint.
8761
8762@menu
8763* Obtaining informations from the daemon::
8764* Submitting data to the daemon::
8765* Customizing the HTML output::
8766@end menu
8767
8768@cindex FCFSD GET requests
8769@node Obtaining informations from the daemon
8770@subsubsection Obtaining informations from the daemon
8771
8772To query the daemon, a GET request must be sent to these endpoints, placing
8773parameters in the address as per the HTTP specification, like so:
8774
8775@example
8776GET /endpoint?param1=value&param2=value
8777@end example
8778
8779Each endpoint will be described using its name (@code{/endpoint} in the
8780example above), followed by the name of each parameter (like @code{param1} and
8781@code{param2}.)
8782
8783@deffn Endpoint /search name
8784This endpoint is used to query about the state of @var{name}, that is, whether
8785it is available for registration or not.
8786
8787The response JSON will contain two fields:
8788
8789@itemize @bullet
8790@item error
8791@item free
8792@end itemize
8793
8794@code{error} can be either the string @code{"true"} or the string
8795@code{"false"}: when @code{"true"}, it means there was an error within the
8796daemon and the name could not be searched at all.
8797
8798@code{free} can be either the string @code{"true"} or the string
8799@code{"false"}: when @code{"true"}, the requested name can be registered.
8800@end deffn
8801
8802@cindex FCFSD POST requests
8803@node Submitting data to the daemon
8804@subsubsection Submitting data to the daemon
8805
8806To send data to the daemon, a POST request must be sent to these endpoints,
8807placing the data to submit in the body of the request, structured using the
8808JSON format, like so:
8809
8810@example
8811POST /endpoint
8812Content-Type: application/json
8813...
8814
8815@{"param1": value1, "param2": value2, ...@}
8816@end example
8817
8818Each endpoint will be described using its name (@code{/endpoint} in the
8819example above), followed by the name of each JSON field (like @code{param1}
8820and @code{param2}.)
8821
8822@deffn Endpoint /register name key
8823This endpoint is used to register a new association between @var{name} and
8824@var{key}.
8825
8826For this operation to succeed, both @var{NAME} and @var{KEY} @strong{must not}
8827be registered already.
8828
8829The response JSON will contain two fields:
8830
8831@itemize @bullet
8832@item error
8833@item message
8834@end itemize
8835
8836@code{error} can be either the string @code{"true"} or the string
8837@code{"false"}: when @code{"true"}, it means the name could not be registered.
8838Clients can get the reason of the failure from the HTTP response code or from
8839the @code{message} field.
8840
8841@code{message} is a string which can be used by clients to let users know the
8842result of the operation. It might be localized to the daemon operator's
8843locale.
8844@end deffn
8845
8846@node Customizing the HTML output
8847@subsubsection Customizing the HTML output
8848
8849In some situations, the daemon will serve HTML documents instead of JSON
8850values. It is possible to configure the daemon to serve custom documents
8851instead of the ones provided with GNUnet, by setting the @code{HTMLDIR} value
8852in its configuration to a directory path.
8853
8854Within the provided path, the daemon will search for these three files:
8855
8856@itemize @bullet
8857@item fcfsd-index.html
8858@item fcfsd-notfound.html
8859@item fcfsd-forbidden.html
8860@end itemize
8861
8862The @file{fcfsd-index.html} file is the daemon's ``homepage'': operators might
8863want to provide informations about the service here, or provide a form with
8864which it is possible to register a name.
8865
8866The @file{fcfsd-notfound.html} file is used primarily to let users know they
8867tried to access an unknown endpoint.
8868
8869The @file{fcfsd-forbidden.html} file is served to users when they try to
8870access an endpoint they should not access. For example, sending an invalid
8871request might result in this page being served.
8872
8739@cindex GNS Namecache 8873@cindex GNS Namecache
8740@node GNS Namecache 8874@node GNS Namecache
8741@section GNS Namecache 8875@section GNS Namecache