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

[FIX] Fix last commit's mistakes

Browse source
This commit is contained in:
lda 2023-09-17 20:20:43 +02:00
parent f15991c737
commit 9bcf45d8eb
6 changed files with 500 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -12,4 +12,3 @@ contrib/.vagrant
src/Schema src/Schema
src/include/Schema src/include/Schema
man/mandoc.db man/mandoc.db
man/*

18
man/man1/http-debug-server.1 Normal file
View file

@ -0,0 +1,18 @@
.Dd $Mdocdate: May 6 2023 $
.Dt HTTP-DEBUG-SERVER 1
.Os Telodendria Project
.Sh NAME
.Nm http-debug-server
.Nd A simple HTTP server that logs requests to the standard output.
.Sh DESCRIPTION
.Pp
.Nm
spins up an HTTP server, listening on port 8008, in the exact same
manner as Telodendria itself. Any request it receives is written to
the standard output, and an empty JSON object is returned to the
client.
.Pp
This command exists just to test the HTTP server API during
development. It probably serves no other practical purpose.
.Sh SEE ALSO
.Xr HttpServer 3

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.

267
man/man1/td.1 Normal file
View file

@ -0,0 +1,267 @@
.Dd $Mdocdate: April 29 2023 $
.Dt TD 1
.Os Telodendria Project
.Sh NAME
.Nm td
.Nd Telodendria build script and patch generation instructions.
.Sh SYNOPSIS
.Nm
.Op recipe
.Sh DESCRIPTION
Telodendria uses a custom build script called
.Nm .
The
.Nm
script is not only a build script, however. It does all kinds of
cool things like format the source code, and generate patch files.
.Nm
is the only supported way to develop Telodendria.
.sp
I opted to write a custom build script instead of just writing a
.Pa Makefile
because I felt that there is really no way to make a truly portable
.Pa Makefile
that could do everything I wanted, with the flexibility I wanted. I
was doing a lot of research on the differences between the GNU and BSD
versions, and I felt it just wasn't worth trying to reconsile the two
when I could write a small and relatively robust POSIX shell script that
would run on both GNU and BSD systems without any problems. I also
think that shell scripts are a lot easier to read than complex
.Pa Makefiles.
They're easier to follow because they're not so cryptic.
.sp
The
.Nm
script is fairly intuitive. It operates somewhat like
.Xr make 1
in that it has recipes that you specify on the command line. To start
using it, just run the following command in the Telodendria source
directory:
.Bd -literal -offset indent
$ . tools/env.sh
.Ed
.sp
.Sy Note:
You will have to run the above command every time you start a new
terminal session, as nothing is persisted to your system. I believe in
non-invasive, fully self-contained tooling, so it is up to you to hook the
Telodendria tools into your environment as you see fit if you want them to
persist.
.sp
If you're going to be submitting patches, you should also configure a
.Pa .env
file in the project directory root, which
.Nm
will include automatically for you. See
.Em FILES
and
.Em ENVIRONMENT .
.sp
Telodendria is designed to be light enough that it can be built from source
on just about any operating system. It only requires an ANSI C compiler and a
standard POSIX environment. To build the Telodendria binary, run
.Nm
with no arguments, or with the
.Pa build
recipe. This will produce
.Pa build/telodendria ,
which you can then install to your system and run as a daemon.
.sp
A complete list of recipes is below. Note that you can run multiple recipes
with a single invocation of
.Nm ,
but recipes are run unconditionally; that is, even if a recipe fails, all the
following recipes are still executed.
.Bl -tag
.It docs
Build the code documentation files. While a good portion of the documentation
is written by hand and maintained in the
.Pa man/
directory, a substantial amount of documentation is stored in the C header
files that define Telodendria's APIs.
This recipe runs
.Xr hdoc 1
on each header to generate man pages for them. The man pages are place in
a directory that's already in your man path.
.It build
Build the source code and generate the output binary. This is the default recipe,
which means it runs if no other recipes are specified. This recipe is incremental;
it only rebuilds sources that have been modifed since the last build, making
subsequent builds faster.
.It run
Run the built binary with the data directory of
.Pa data/
in the current directory. This recipe is used for quick testing during
development. It is
.Sy not
the recommended way to run Telodendria in a production environment; it should only
be used for development.
.It clean
Remove the
.Pa build/
directory. The build recipe does not place anything outside of
.Pa build/ ,
so you can usually just delete that directory and get the same effect.
.It license
Update the copyright comments in every C source and header file using the
contents of the
.Pa LICENSE.txt
file. This recipe will also add the license header to new headers and C
sources that show up.
.It format
Format the code using the system's
.Xr indent 1 .
This should be run before generating patch files, to ensure that the code follows
the project conventions. Note that the provided
.Pa .indent.pro
assumes an OpenBSD indent, which may cause the GNU implementation to choke. In
that case, don't send patch files with totally different formatting; just submit
the patch as-is and they will get formatted before committing.
.It site
Deploy the Telodendria website by generating HTML files for the documentation,
and copying them along with the front page to the specified web root. This is
used to deploy the official website, but it could be used to deploy a local
development site as necessary. See
.Em ENVIRONMENT .
.It release
Generate a release tarball, checksum and sign it, and push it to the web root.
See the relevant environment variables below.
.It patch
Generate a formatted patch file. The Telodendria project isn't super picky about
how patches look as long as they apply cleanly, but this recipe generates patches
in the format we like them, and is therefore recommended. It makes patches easy
to read. This recipe will use your configured editor to open your formatted patch
so you can review and edit it as necessary before sending it off.
.It diff
Generate a temporary preview patch that is opened in the system pager. This can
be used for quickly quickly previewing your changes and the patch file you'll
be creating.
.El
.sp
.Sh ENVIRONMENT
Any of the following environment variables are used in the build recipes.
They can all be specified in your shell when invoking
.Nm ,
or they can be placed in a
.Pa .env
file. For most of these variables, if you would like to append or prepend
to the default values, do so in the
.Pa .env
file, which is sourced after the defaults are set, allowing you to reference
the default values in your new value.
.Bl -tag
.It Ev CC
The C compiler to use. This defaults to
.Pa cc,
which is usually a symlink to your system's preferred compiler. If for some
reason you want to use a diferent compiler, do so with this environment
variable.
.It Ev PREFIX
When installing/uninstalling Telodendria, the systeme prefix to use. This
defaults to
.Pa /usr/local .
.It Ev CFLAGS
The compiler flags used to generate object files.
.Nm
comes with reasonable defaults that shouldn't need to be changed in most
scenarios, but if you do need to change the compiler flags, you can do
so with this environment variable.
.It Ev LDFLAGS
The compiler flags used to link the object files to create an output
binary.
.It Ev LD_EXTRA
The common, well-known compilers support a number of extra flags that
smaller, niche compilers probably will not. This variable holds those
flags, so if you are compiling with a small, lesser known compiler, you
can set this to an empty string to disable the extra flags.
.Pp
.Nm
comes with reasonable defaults that shouldn't need to be changed in most
scenarios, but if you need to change the linker flags, you do so with this
environment variable.
.It Ev TLS_IMPL
Set the TLS implementation library to use for Telodendria's TLS
support. Consult
.Xr Tls 3
for a list of supported implementations. Implementations should be
specified by name in all uppercase.
.It Ev PROG
The name of the output binary. This defaults to
.Pa build/telodendria.
.It Ev DEFINES
Global preprocessor definitions to append to
.Ev CFLAGS.
This is just kept separate to keep things organized.
.It Ev INCLUDES
Header directories to make available. This is appended to
.Ev CFLAGS,
it is just kept separate to keep things organized.
.It Ev DEBUG
If set to "1", append some debug flags to
.Ev CFLAGS
and whipe out any
.Ev LDFLAGS
that awould cause the output binary to be optimized in any way. This also
depends "-debug" to
.Ev PROG .
.It Ev TELODENDRIA_VERSION
This variable does make its way into the output binary, but it is primarily
used for generating and publishing releases. This variable affects the
.Sy release
recipe.
.It Ev TELODENDRIA_PUB
The web root where the Telodendria website lives. This is where the site
is pushed to, and where generated releases go.
.It Ev PATCHSET
This variable restricts the files that
.Nm
operates on when generating patches or diffs. If you only want to generate
a diff or patch for a certain file, directory, or collection of files and
directories, set this variable to those files and directories, separated
by a space. You can mix files and directories as necessary.
.It Ev MXID
Your Matrix ID in standard format. This is used when generating patches,
so that you can be assigned credit for your patches, as well as be contacted
about your patches.
.Nm
will automatically deduce this from your system, but it will most
likely get it wrong. Please make sure you are reachable at this ID.
.It Ev DISPLAY_NAME
The display name you want to appear on your patches. This should probably
match your Matrix display name, although it doesn't necessarily have to.
.Nm
will deduce this from your system, and if you set it up properly, you may
not even have to set this variable. If
.Nm
gets it wrong, this allows you to override your display name.
.It Ev EDITOR
Your preferred editor for writing patch file descriptions. This can be a
GUI or terminal editor. If unset, this defaults to the system's
.Xr vi 1
editor.
.It Ev PAGER
Your preferred pager for previewing patches. If left unset, this defaults
to
.Xr less 1 .
.Sh FILES
.Bl -tag
.It Pa .env
An environment file that contains lines in the form of
.Pa VARIABLE=value
with environment variables to set in the
.Nm
script. See
.Em ENVIRONMENT .
Note that
.Nm
simply sources this file, which means that any shell code in it will be
executed each time
.Nm
is invoked.
.Sh EXIT STATUS
.Sh HISTORY
.Sh BUGS
.Nm
unconditionally exits with code 0, even if errors occurred. Furthermore,
recipes are run unconditionally, regardless of whether or not any recipes
before have failed.

34
man/man1/tt.1 Normal file
View file

@ -0,0 +1,34 @@
.Dd $Mdocdate: April 29 2023 $
.Dt TT 1
.Os Telodendria Project
.Sh NAME
.Nm tt
.Nd Make authenticated Matrix requests.
.Sh SYNPOSIS
.Nm
.Op request-path
.Sh DESCRIPTION
.Nm
is an extremely simple wrapper over
.Xr http 1
and
.Xr json 1
that automatically registers a user and continues to log in as that
user. It obtains an access token that it uses to authenticate the
given request, and then logs out when the request has completed. It
also doesn't require the whole URL to be typed; only the path name
is needed.
.Sh ENVIRONMENT
.Bl -tag
.It Ev METH
The request method to use for the user-specified request.
.It Ev DATA
The data to pass to
.Xr http 1 .
This can either be a string, or a file. Consult the
.Xr http 1
page for details.
.El
.Sh SEE ALSO
.Xr http 1 ,
.Xr json 1