diff --git a/.gitignore b/.gitignore index c0d6bc5..7d63ee8 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,3 @@ contrib/.vagrant src/Schema src/include/Schema man/mandoc.db -man/* diff --git a/man/man1/http-debug-server.1 b/man/man1/http-debug-server.1 new file mode 100644 index 0000000..f8c02da --- /dev/null +++ b/man/man1/http-debug-server.1 @@ -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 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/man1/td.1 b/man/man1/td.1 new file mode 100644 index 0000000..15bb994 --- /dev/null +++ b/man/man1/td.1 @@ -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. diff --git a/man/man1/tt.1 b/man/man1/tt.1 new file mode 100644 index 0000000..3b83bf5 --- /dev/null +++ b/man/man1/tt.1 @@ -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