plate/telodendria
1
0
Fork 0
forked from lda/telodendria
Code Pull requests Activity Actions

Add some more documentation.

Browse source
This commit is contained in:
Jordan Bancino 2023-03-12 03:36:19 +00:00
parent b4a394c44b
commit aba1ef9251
6 changed files with 382 additions and 8 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

70
man/man1/http.1 Normal file
View file

@ -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

111
man/man1/json.1 Normal file
View file

@ -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.

17
man/man3/Http.3
View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: December 13 2022 $ .Dd $Mdocdate: March 12 2023 $
.Dt HTTP 3 .Dt HTTP 3
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -20,6 +20,8 @@
.Fn HttpParamDecode "char *" .Fn HttpParamDecode "char *"
.Ft char * .Ft char *
.Fn HttpParamEncode "HashMap *" .Fn HttpParamEncode "HashMap *"
.Ft HashMap *
.Fn HttpParseHeaders "FILE *"
.Sh DESCRIPTION .Sh DESCRIPTION
.Pp .Pp
.Nm .Nm
@ -148,6 +150,19 @@ and
.Fn HttpParamEncode .Fn HttpParamEncode
convert HTTP parameters in the form of "param=value&param2=val2" convert HTTP parameters in the form of "param=value&param2=val2"
to and from a hash map for easy parsing, manipulation, and encoding. 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 .Sh RETURN VALUES
.Pp .Pp
.Fn HttpStatusToString .Fn HttpStatusToString

25
man/man3/Json.3
View file

@ -1,4 +1,4 @@
.Dd $Mdocdate: March 6 2023 $ .Dd $Mdocdate: March 12 2023 $
.Dt JSON 3 .Dt JSON 3
.Os Telodendria Project .Os Telodendria Project
.Sh NAME .Sh NAME
@ -41,9 +41,9 @@
.Ft void .Ft void
.Fn JsonEncodeString "const char *" "FILE *" .Fn JsonEncodeString "const char *" "FILE *"
.Ft void .Ft void
.Fn JsonEncodeValue "JsonValue *" "FILE *" .Fn JsonEncodeValue "JsonValue *" "FILE *" "int"
.Ft int .Ft int
.Fn JsonEncode "HashMap *" "FILE *" .Fn JsonEncode "HashMap *" "FILE *" "int"
.Ft HashMap * .Ft HashMap *
.Fn JsonDecode "FILE *" .Fn JsonDecode "FILE *"
.Ft JsonValue * .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 API so that it is accessible to custom JSON encoders. Normal users
that are not writing custom encoders should in most cases just use that are not writing custom encoders should in most cases just use
.Fn JsonEncode .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 .Pp
.Fn JsonEncode .Fn JsonEncode
encodes a JSON object as minimized JSON and writes it to the given encodes a JSON object as minimized JSON and writes it to the given
output stream. This function is recursive; it will serialize 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 .Fn JsonDecode
does the opposite; it reads from a JSON stream and decodes it does the opposite of
into a hash map of JsonValues. .Fn JsonEncode ;
it reads from a JSON stream and decodes it into a hash map
of JsonValues.
.Pp .Pp
.Fn JsonSet .Fn JsonSet
and and

74
man/man3/Main.3 Normal file
View file

@ -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.

93
man/man3/Telodendria.3 Normal file
View file

@ -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