diff options
author | Alessio Vanni <vannilla@firemail.cc> | 2021-05-16 23:07:03 +0200 |
---|---|---|
committer | Alessio Vanni <vannilla@firemail.cc> | 2021-05-16 23:07:03 +0200 |
commit | c68abd271cce537ced900193e59a7d5373c1bf83 (patch) | |
tree | 83babf83bba60e0c8046f1dbf8071fe41b54cd47 /doc | |
parent | 8cee30bb827c253ea924fd3397558bfec86902b8 (diff) | |
download | gnunet-c68abd271cce537ced900193e59a7d5373c1bf83.tar.gz gnunet-c68abd271cce537ced900193e59a7d5373c1bf83.zip |
[FCFSD] document it in the handbook
Diffstat (limited to 'doc')
-rw-r--r-- | doc/handbook/chapters/developer.texi | 134 |
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 | |||
8736 | gnunet-namestore. In the future a solution that uses the C API would be cleaner | 8737 | gnunet-namestore. In the future a solution that uses the C API would be cleaner |
8737 | and better. | 8738 | and better. |
8738 | 8739 | ||
8740 | @node Registering names using the FCFS daemon | ||
8741 | @subsection Registering names using the FCFS daemon | ||
8742 | |||
8743 | This section describes FCFSD, a daemon used to associate names with PKEY | ||
8744 | records following a ``First Come, First Served'' policy. This policy means | ||
8745 | that a certain name can not be registered again if someone registered it | ||
8746 | already. | ||
8747 | |||
8748 | The daemon can be started by using @code{gnunet-namestore-fcfsd}, which will | ||
8749 | start a simple HTTP server on localhost, using a port specified by the | ||
8750 | @code{HTTPORT} value in its configuration. | ||
8751 | |||
8752 | Communication is performed by sending GET or POST requests to specific paths | ||
8753 | (``endpoints''), as described in the following sections. | ||
8754 | |||
8755 | The daemon will always respond with data structured using the JSON format. | ||
8756 | The fields to be expected will be listed for each endpoint. | ||
8757 | |||
8758 | The only exceptions are for the ``root'' endpoint (i.e. @code{/}) which will | ||
8759 | return a HTML document, and two other HTML documents which will be served when | ||
8760 | certain 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 | |||
8772 | To query the daemon, a GET request must be sent to these endpoints, placing | ||
8773 | parameters in the address as per the HTTP specification, like so: | ||
8774 | |||
8775 | @example | ||
8776 | GET /endpoint?param1=value¶m2=value | ||
8777 | @end example | ||
8778 | |||
8779 | Each endpoint will be described using its name (@code{/endpoint} in the | ||
8780 | example above), followed by the name of each parameter (like @code{param1} and | ||
8781 | @code{param2}.) | ||
8782 | |||
8783 | @deffn Endpoint /search name | ||
8784 | This endpoint is used to query about the state of @var{name}, that is, whether | ||
8785 | it is available for registration or not. | ||
8786 | |||
8787 | The 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 | ||
8796 | daemon 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 | |||
8806 | To send data to the daemon, a POST request must be sent to these endpoints, | ||
8807 | placing the data to submit in the body of the request, structured using the | ||
8808 | JSON format, like so: | ||
8809 | |||
8810 | @example | ||
8811 | POST /endpoint | ||
8812 | Content-Type: application/json | ||
8813 | ... | ||
8814 | |||
8815 | @{"param1": value1, "param2": value2, ...@} | ||
8816 | @end example | ||
8817 | |||
8818 | Each endpoint will be described using its name (@code{/endpoint} in the | ||
8819 | example above), followed by the name of each JSON field (like @code{param1} | ||
8820 | and @code{param2}.) | ||
8821 | |||
8822 | @deffn Endpoint /register name key | ||
8823 | This endpoint is used to register a new association between @var{name} and | ||
8824 | @var{key}. | ||
8825 | |||
8826 | For this operation to succeed, both @var{NAME} and @var{KEY} @strong{must not} | ||
8827 | be registered already. | ||
8828 | |||
8829 | The 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. | ||
8838 | Clients can get the reason of the failure from the HTTP response code or from | ||
8839 | the @code{message} field. | ||
8840 | |||
8841 | @code{message} is a string which can be used by clients to let users know the | ||
8842 | result of the operation. It might be localized to the daemon operator's | ||
8843 | locale. | ||
8844 | @end deffn | ||
8845 | |||
8846 | @node Customizing the HTML output | ||
8847 | @subsubsection Customizing the HTML output | ||
8848 | |||
8849 | In some situations, the daemon will serve HTML documents instead of JSON | ||
8850 | values. It is possible to configure the daemon to serve custom documents | ||
8851 | instead of the ones provided with GNUnet, by setting the @code{HTMLDIR} value | ||
8852 | in its configuration to a directory path. | ||
8853 | |||
8854 | Within 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 | |||
8862 | The @file{fcfsd-index.html} file is the daemon's ``homepage'': operators might | ||
8863 | want to provide informations about the service here, or provide a form with | ||
8864 | which it is possible to register a name. | ||
8865 | |||
8866 | The @file{fcfsd-notfound.html} file is used primarily to let users know they | ||
8867 | tried to access an unknown endpoint. | ||
8868 | |||
8869 | The @file{fcfsd-forbidden.html} file is served to users when they try to | ||
8870 | access an endpoint they should not access. For example, sending an invalid | ||
8871 | request 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 |