forked from Telodendria/Telodendria
Add some more documentation.
This commit is contained in:
parent
b4a394c44b
commit
aba1ef9251
|
|
@ -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
|
||||
|
|
@ -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.
|
||||
|
|
@ -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¶m2=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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue