From aba1ef9251a3aa02d3ec15c4f99a260627fbf08e Mon Sep 17 00:00:00 2001
From: Jordan Bancino <jordan@bancino.net>
Date: Sun, 12 Mar 2023 03:36:19 +0000
Subject: [PATCH] Add some more documentation.

---
 man/man1/http.1        |  70 ++++++++++++++++++++++++++
 man/man1/json.1        | 111 +++++++++++++++++++++++++++++++++++++++++
 man/man3/Http.3        |  17 ++++++-
 man/man3/Json.3        |  25 +++++++---
 man/man3/Main.3        |  74 +++++++++++++++++++++++++++
 man/man3/Telodendria.3 |  93 ++++++++++++++++++++++++++++++++++
 6 files changed, 382 insertions(+), 8 deletions(-)
 create mode 100644 man/man1/http.1
 create mode 100644 man/man1/json.1
 create mode 100644 man/man3/Main.3
 create mode 100644 man/man3/Telodendria.3

diff --git a/man/man1/http.1 b/man/man1/http.1
new file mode 100644
index 0000000..3a108e9
--- /dev/null
+++ b/man/man1/http.1
@@ -0,0 +1,70 @@
+.Dd $Mdocdate: March 12 2023 $
+.Dt HTTP 1
+.Os Telodendria Project
+.Sh NAME
+.Nm http
+.Nd A simple command line utility for making HTTP requests.
+.Sh SYNOPSIS
+.Nm
+.Op Fl i
+.Op Fl X Ar method
+.Op Fl H Ar header
+.Op Fl d Ar data
+.Op URL
+.Sh DESCRIPTION
+.Nm
+Is a command line HTTP client. It is very heavily inspired by
+.Xr curl 1 ,
+and even uses the same flag names when possible. However,
+.Nm
+is designed to be much simpler than
+.Xr curl 1 ,
+and is built on Telodendria's own
+.Xr HttpClient 3
+API. It primarily exists to test
+.Xr HttpClient 3
+and
+.Xr HttpServer 3 ,
+and make development of Telodendria possible without having
+to install any external tools.
+.sp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl i
+Display the response headers before writing the body.
+.It Fl X Ar method
+Set the request method. This can be any of the options
+allowed by the
+.Xr Http 3
+API; unlike
+.Xr curl 1 ,
+it cannot be any arbitrary string.
+.It Fl H Ar header
+Set a request header, in the form of ``Header: value''. This option
+can be set multiple times to add multiple request headers.
+.It Fl d Ar data
+Send data to the server in the request body. If
+.Ar data
+starts with ``@'', then the file specified after is opened
+and read in. If it is ``@-'', then standard input is used.
+Otherwise, the string is passed to the server as-is.
+.El
+.Pp
+.Nm
+also requires a
+.Ar URL
+to make the request to. The URL is parsed by the
+.Xr Uri 3
+API, so consult that page for the syntax of URLs.
+.Sh EXIT STATUS
+.Nm
+exits with
+.Va EXIT_SUCCESS
+if all command line options were valid, the request was
+made successfully, and the server returns an HTTP code
+that indicates success. It exits with
+.Va EXIT_FAILURE
+in all other scenarios.
+.Sh SEE ALSO
+.Xr HttpClient 3 ,
+.Xr Uri 3
diff --git a/man/man1/json.1 b/man/man1/json.1
new file mode 100644
index 0000000..7ed18c3
--- /dev/null
+++ b/man/man1/json.1
@@ -0,0 +1,111 @@
+.Dd $Mdocdate: March 12 2023 $
+.Dt JSON 1
+.Os Telodendria Project
+.Sh NAME
+.Nm json
+.Nd A simple command line utility for parsing and generating JSON.
+.Sh SYNOPSIS
+.Nm
+.Op Fl s Ar query
+.Op Fl e Ar str
+.Sh DESCRIPTION
+.Nm
+is a simple command line utility for dealing with JSON. It is
+somewhat inspired by
+.Xr jq 1 ,
+but is not compatible in any way with it.
+.Nm
+is designed to be much simpler than
+.Xr jq 1 ,
+and is built on Telodendria's own
+.Xr Json 3
+API. It primarily exists to ease development of Telodendria, and
+to make development possible without having to install any external
+tools.
+.Pp
+The options are as follows. Unless stated otherwise, these options
+are mutually exclusive, and the last one specified takes precedence.
+All positional parameters are ignored.
+.Bl -tag -width Ds
+.It Fl s Ar query
+Use
+.Va query
+to query a field from a JSON object given on the standard input.
+The query syntax very vaguely resembles C code, but it is much
+more primitive. Multiple queries are separated by an arrow
+(``->''). This makes it trivial to drill down into nested
+objects and arrays.
+.Pp
+To select a value from an object, just specify the key. To select
+an element from an array specify the key whose value is the array,
+and then use the C square bracket syntax to select an element.
+.Pp
+A number of ``functions'' exist to make
+.Nm
+more versatile. Functions are called by prefacing the key with
+a ``@'' symbol. Functions can appear anywhere in the query, provided
+they make sense within the context of the JSON object being processed.
+The available functions are as follows:
+.Bl -tag -width Ds
+.It keys
+When applied to an object, outputs an array of keys.
+.It length
+When applied to an array, outputs the number of elements in the
+array. When applied to a string, returns the number of bytes
+needed to store the decoded version of the string.
+.It decode
+When applied to a string, outputs the decoded version of the
+string.
+.El
+.Pp
+When a key is prefaced with the ``^'' symbol, then instead of getting
+the value at that key, it is removed from the object, and the new
+object is passed along. 
+.It Fl e Ar str
+Encode
+.Va str
+as a JSON string and print it to standard output. This is useful for
+generating JSON with shell scripts.
+.El
+.Pp
+If no options are specified, then the default behavior of
+.Nm
+is to read a JSON object given on the standard input and pretty-print
+it to the standard output, or print an error to standard error if
+the given input is invalid.
+.Sh EXAMPLES
+.Pp
+Get the error string of an error returned by a Matrix API endpoint:
+.Bd -literal -offset indent
+json -s 'error->@decode'
+.Ed
+.Pp
+Get the number of stages in the first flow listed in a list
+of user-interactive authentication flows:
+.Bd -literal -offset indent
+json -s 'flows[0]->stages->@length'
+.Ed
+.Pp
+Get the first stage of the first flow listed in a list
+of user-interactive authentication flows:
+.Bd -literal -offset indent
+json -s 'flows[0]->stages[0]->@decode'
+.Ed
+.Pp
+List the keys in a JSON object:
+.Bd -literal -offset indent
+json -s '@keys'
+.Ed
+.Pp
+Get the number of keys in a JSON object:
+.Bd -literal -offset indent
+json -s '@keys->@length'
+.Ed
+.Sh EXIT STATUS
+.Nm
+exits with
+.Va EXIT_SUCCESS
+if all command line options were valid and the given JSON object
+parses successfully. It exits with
+.Va EXIT_FAILURE
+in all other scenarios.
diff --git a/man/man3/Http.3 b/man/man3/Http.3
index 12c5063..ff30642 100644
--- a/man/man3/Http.3
+++ b/man/man3/Http.3
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: December 13 2022 $
+.Dd $Mdocdate: March 12 2023 $
 .Dt HTTP 3
 .Os Telodendria Project
 .Sh NAME
@@ -20,6 +20,8 @@
 .Fn HttpParamDecode "char *"
 .Ft char *
 .Fn HttpParamEncode "HashMap *"
+.Ft HashMap *
+.Fn HttpParseHeaders "FILE *"
 .Sh DESCRIPTION
 .Pp
 .Nm
@@ -148,6 +150,19 @@ and
 .Fn HttpParamEncode
 convert HTTP parameters in the form of "param=value&param2=val2"
 to and from a hash map for easy parsing, manipulation, and encoding.
+.Pp
+.Fn HttpParseHeaders
+reads HTTP headers from a stream and returns a hash map
+of keys and values. All keys are lowercased to make
+querying them consistent and not dependent on the casing
+that was read from the stream. This is useful for both
+client and server code, since the headers are of the same
+format. This function should be used after parsing the
+HTTP status line, because it does not parse that line.
+It will stop when it encounters the first blank line,
+which indicates that the body is beginning. After this
+function completes, the body may be immediately be read
+from the stream without any additional processing.
 .Sh RETURN VALUES
 .Pp
 .Fn HttpStatusToString
diff --git a/man/man3/Json.3 b/man/man3/Json.3
index 368bec5..09989f4 100644
--- a/man/man3/Json.3
+++ b/man/man3/Json.3
@@ -1,4 +1,4 @@
-.Dd $Mdocdate: March 6 2023 $
+.Dd $Mdocdate: March 12 2023 $
 .Dt JSON 3
 .Os Telodendria Project
 .Sh NAME
@@ -41,9 +41,9 @@
 .Ft void
 .Fn JsonEncodeString "const char *" "FILE *"
 .Ft void
-.Fn JsonEncodeValue "JsonValue *" "FILE *"
+.Fn JsonEncodeValue "JsonValue *" "FILE *" "int"
 .Ft int
-.Fn JsonEncode "HashMap *" "FILE *"
+.Fn JsonEncode "HashMap *" "FILE *" "int"
 .Ft HashMap *
 .Fn JsonDecode "FILE *"
 .Ft JsonValue *
@@ -190,15 +190,26 @@ from the given  value. This function is exposed via the public
 API so that it is accessible to custom JSON encoders. Normal users
 that are not writing custom encoders should in most cases just use
 .Fn JsonEncode
-to encode an entire object.
+to encode an entire object. The third parameter is an integer that
+represents the indent level of the value to be printed, or a negative
+number if pretty-printing should be disabled, and JSON should be
+printed as minimized as possible. If you want to pretty-print a
+JSON object, set this to
+.Va JSON_PRETTY .
+To get the minified output, set it to
+.Va JSON_DEFAULT .
 .Pp
 .Fn JsonEncode
 encodes a JSON object as minimized JSON and writes it to the given
 output stream. This function is recursive; it will serialize
-everything accessible from the passed object.
+everything accessible from the passed object. The third integer
+parameter has the same behavior asa described above.
+.Pp
 .Fn JsonDecode
-does the opposite; it reads from a JSON stream and decodes it
-into a hash map of JsonValues.
+does the opposite of
+.Fn JsonEncode ;
+it reads from a JSON stream and decodes it into a hash map
+of JsonValues.
 .Pp
 .Fn JsonSet
 and
diff --git a/man/man3/Main.3 b/man/man3/Main.3
new file mode 100644
index 0000000..ddd2d0f
--- /dev/null
+++ b/man/man3/Main.3
@@ -0,0 +1,74 @@
+.Dd $Mdocdate: March 12 2023 $
+.Dt MAIN 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Main
+.Nd Telodendria daemon entry function.
+.Sh DESCRIPTION
+.Pp
+The
+.Fn main
+function is the first function that is executed. It is responsible
+for setting things up and tearing them down. In order, it:
+.Bl -bullet
+.It
+Creates a default logging configuration, installs the memory hook,
+and prints the header.
+.It
+If running on OpenBSD, or is patched for other operating systems
+that support it, executes
+.Xr pledge 2
+with a minimal set of permissions for security.
+.It
+Parses the command line arguments and sets the relevant flags.
+.It
+If running on OpenBSD, or is patched for other operating systems
+that support it, executes
+.Xr unveil 2
+on the configuration file.
+.It
+parses and processes the configuration file.
+.It
+If running on OpenBSD, or is patched for other operating systems
+that support it, executes
+.Xr unveil 2
+on the data directory, and then disables all future calls to
+.Xr unveil 2 .
+.It
+Applies all settings from the configuration file.
+.It
+Changes into the data directory.
+.It
+Binds the HTTP socket.
+.It
+If running as the root user and not on OpenBSD or other operating
+systems that support
+.Xr unveil 2 ,
+executes
+.Xr chroot 2
+on the data directory.
+.It
+Detects the running user, and\(emif specified in the
+configuration\(emdrops permissions.
+.It
+Sets up the database, and cron runner, then starts
+the HTTP server and installs the signal handlers.
+.It
+Blocks on the HTTP server.
+.It
+Shuts down the HTTP server, cleans up all memory and
+file handles, then exits.
+.El
+.Sh RETURN VALUE
+.Pp
+.Fn main
+returns
+.Va EXIT_SUCCESS
+if everything runs correctly and Telodendria is
+quit normally. It returns
+.Va EXIT_FAILURE
+if there was a fatal failure before the HTTP
+server could be started.
+.Pp
+These values are returned to the operating system and
+indicate the exit status of the process.
diff --git a/man/man3/Telodendria.3 b/man/man3/Telodendria.3
new file mode 100644
index 0000000..9711122
--- /dev/null
+++ b/man/man3/Telodendria.3
@@ -0,0 +1,93 @@
+.Dd $Mdocdate: March 12 2023 $
+.Dt TELODENDRIA 3
+.Os Telodendria Project
+.Sh NAME
+.Nm Telodendria
+.Nd Branding and callback functions specific to Telodendria.
+.Sh SYNOPSIS
+.In Telodendria.h
+.Vt const char
+.Va TelodendriaLogo[][]
+.Pp
+.Vt const char
+.Va TelodendriaHeader[][]
+.Pp
+.Ft void
+.Fn TelodendriaHexDump "size_t" "char *" "char *" "void *"
+.Ft void
+.Fn TelodendriaMemoryHook "MemoryAction" "MemoryInfo *" "void *"
+.Ft void
+.Fn TelodendriaMemoryIterator "MemoryInfo *" "void *"
+.Ft void
+.Fn TelodendriaPrintHeader "LogConfig *"
+.Sh DESCRIPTION
+.Pp
+This API provides the callbacks used to hook Telodendria into
+the various other APIs. It exists primarily to be called by
+.Fn main ,
+but these functions are not static so that
+.Fn
+main can be in a separate compilation unit.
+.Pp
+.Va TelodendriaLogo
+and
+.Va TelodendriaHeader
+are
+.Va TELODENDRIA_LOGO_HEIGHT
+by
+.Va TELODENDRIA_LOGO_WIDTH
+and
+.Va TELODENDRIA_HEADER_HEIGHT
+by
+.Va TELODENDRIA_HEADER_WIDTH
+character arrays, respectively. They hold C strings that
+are used to generate the logo and header.
+.Sy NOTE:
+the Telodendria logo belong solely to the Telodendria
+project. If this code is modified and distributed as a
+package other than the official Telodendria source
+package, the logo must be replaced with a different
+one, or removed entirely. Consult the license section
+of 
+.Xr Telodendria 7
+for details.
+.Pp
+.Fn TelodendriaHexDump
+follows the function prototype required by the
+.Fn MemoryHexDump
+function, documented in
+.Xr Memory 3 .
+This function is responsible for outputting memory
+hex dumps to the log.
+Its fourth parameter is cast to a LogConfig object,
+so one should be passed into the
+.Fn MemoryHexDump
+function.
+.Pp
+.Fn TelodendriaMemoryIterator
+follows the function prototype required by the
+.Fn MemoryIterate
+function, documented in
+.Xr Memory 3 .
+This function is executed at the end of the program's
+execution and detects leaks that occurred during normal
+operation.
+.Pp
+.Fn TelodendriaMemoryHook
+follows the function prototype required by the
+.Fn MemoryHook
+function, documented in
+.Xr Memory 3 .
+This function is executed every time an allocation,
+re-allocation, or free occurs, and is responsible for
+logging memory operations to the log.
+.Pp
+.Fn TelodendriaPrintHeader
+prints the logo and header, along with the copyright
+year and holder, and version number out to the log.
+.Sh RETURN VALUES
+.Pp
+None of the functions in this API return anything.
+.Sh SEE ALSO
+.Xr Memory 3 ,
+.Xr Log 3