forked from lda/telodendria
[FIX] Fix gitignore a bit, and remove man pages
This commit is contained in:
parent
e4ee22fa73
commit
f15991c737
6 changed files with 1 additions and 500 deletions
1
.gitignore
vendored
1
.gitignore
vendored
|
|
@ -12,3 +12,4 @@ contrib/.vagrant
|
|||
src/Schema
|
||||
src/include/Schema
|
||||
man/mandoc.db
|
||||
man/*
|
||||
|
|
|
|||
|
|
@ -1,18 +0,0 @@
|
|||
.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
|
||||
|
|
@ -1,70 +0,0 @@
|
|||
.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
111
man/man1/json.1
|
|
@ -1,111 +0,0 @@
|
|||
.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
267
man/man1/td.1
|
|
@ -1,267 +0,0 @@
|
|||
.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.
|
||||
|
|
@ -1,34 +0,0 @@
|
|||
.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
|
||||
Loading…
Reference in a new issue