From e0c94d7bd2a0a3ec089de02603c70f89df4fa338 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Sat, 29 Apr 2023 18:39:01 +0000 Subject: [PATCH] Site now pulls built man pages. --- TODO.txt | 8 +- src/HeaderParser.c | 3 +- src/include/Config.h | 4 +- src/include/Stream.h | 212 ++++++++++++++++++++++++++++++++++--------- src/include/Tls.h | 88 ++++++++++++++---- src/include/Uri.h | 32 ++++++- src/include/User.h | 11 ++- tools/bin/man-table | 2 +- tools/bin/td | 18 +++- 9 files changed, 296 insertions(+), 82 deletions(-) diff --git a/TODO.txt b/TODO.txt index d8e93e7..d2afec0 100644 --- a/TODO.txt +++ b/TODO.txt @@ -23,17 +23,17 @@ Milestone: v0.3.0 [ ] Documentation [x] Array [x] Io - [ ] Stream - [ ] Tls + [x] Stream + [x] Tls [x] HttpClient - [ ] Uri + [x] Uri [ ] td [ ] tt [ ] http-debug-server [ ] tp [ ] send-patch [x] Log - [ ] TelodendriaConfig -> Config + [x] TelodendriaConfig -> Config [x] HashMap [x] HttpRouter [x] Html diff --git a/src/HeaderParser.c b/src/HeaderParser.c index 0977788..7fb2c56 100644 --- a/src/HeaderParser.c +++ b/src/HeaderParser.c @@ -511,7 +511,8 @@ HeaderParse(Stream * stream, HeaderExpr * expr) if (strcmp(word, "struct") == 0 || strcmp(word, "enum") == 0 || - strcmp(word, "const") == 0) + strcmp(word, "const") == 0 || + strcmp(word, "unsigned") == 0) { Free(word); word = HeaderConsumeWord(expr); diff --git a/src/include/Config.h b/src/include/Config.h index 2bb0c8a..ce1a762 100644 --- a/src/include/Config.h +++ b/src/include/Config.h @@ -120,14 +120,14 @@ typedef struct Config * set the ok flag to 0. The caller should always check the ok flag, * and if there is an error, it should display the error to the user. */ -Config * ConfigParse(HashMap *); +extern Config * ConfigParse(HashMap *); /** * Free all the values inside of the given configuration structure, * as well as the structure itself, such that it is completely invalid * when this function returns. */ -void ConfigFree(Config *); +extern void ConfigFree(Config *); /** * Check whether or not the configuration exists in the database, diff --git a/src/include/Stream.h b/src/include/Stream.h index 8293ace..894ebf9 100644 --- a/src/include/Stream.h +++ b/src/include/Stream.h @@ -24,76 +24,200 @@ #ifndef TELODENDRIA_STREAM_H #define TELODENDRIA_STREAM_H +/*** + * @Nm Stream + * @Nd An abstraction over the Io API that implements standard C I/O. + * @Dd April 29 2023 + * @Xr Io + * + * .Nm + * implements an abstraction layer over the Io API. This layer buffers + * I/O and makes it much easier to work with, mimicking the standard + * C library and offering some more convenience features. + */ + #include #include +/** + * An opaque structure analogous to C's FILE pointers. + */ typedef struct Stream Stream; -extern Stream * - StreamIo(Io * io); +/** + * Create a new stream using the specified Io for underlying I/O + * operations. + */ +extern Stream * StreamIo(Io * io); -extern Stream * - StreamFd(int); +/** + * Create a new stream using the specified POSIX file descriptor. + * This is a convenience function for calling + * .Fn IoFd + * and then passing the result into + * .Fn StreamIo . + */ +extern Stream * StreamFd(int); -extern Stream * - StreamFile(FILE *); +/** + * Create a new stream using the specified C FILE pointer. This is a + * convenience function for calling + * .Fn IoFile + * and then passing the result into + * .Fn StreamIo . + */ +extern Stream * StreamFile(FILE *); -extern Stream * - StreamOpen(const char *, const char *); +/** + * Create a new stream using the specified path and mode. This is a + * convenience function for calling + * .Xr fopen 3 + * and then passing the result into + * .Fn StreamFile . + */ +extern Stream * StreamOpen(const char *, const char *); -extern Stream * - StreamStdout(void); +/** + * Get a stream that writes to the standard output. + */ +extern Stream * StreamStdout(void); -extern Stream * - StreamStderr(void); +/** + * Get a stream that writes to the standard error. + */ +extern Stream * StreamStderr(void); -extern Stream * - StreamStdin(void); +/** + * Get a stream that reads from the standard input. + */ +extern Stream * StreamStdin(void); -extern int - StreamClose(Stream *); +/** + * Close the stream. This flushes the buffers and closes the underlying + * Io. It is analogous to the standard + * .Xr fclose 3 + * function. + */ +extern int StreamClose(Stream *); -extern int - StreamVprintf(Stream *, const char *, va_list); +/** + * Print a formatted string. This function is analogous to the standard + * .Xr vfprintf 3 + * function. + */ +extern int StreamVprintf(Stream *, const char *, va_list); -extern int - StreamPrintf(Stream *, const char *,...); +/** + * Print a formatted string. This function is analogous to the + * standard + * .Xr fprintf 3 + * function. + */ +extern int StreamPrintf(Stream *, const char *,...); -extern int - StreamGetc(Stream *); +/** + * Get a single character from a stream. This function is analogous to + * the standard + * .Xr fgetc 3 + * function. + */ +extern int StreamGetc(Stream *); -extern int - StreamUngetc(Stream *, int); +/** + * Push a character back onto the input stream. This function is + * analogous to the standard + * .Xr ungetc 3 + * function. + */ +extern int StreamUngetc(Stream *, int); -extern int - StreamPutc(Stream *, int); +/** + * Write a single character to the stream. This function is analogous + * to the standard + * .Xr fputc 3 + * function. + */ +extern int StreamPutc(Stream *, int); -extern int - StreamPuts(Stream *, char *); +/** + * Write a null-terminated string to the stream. This function is + * analogous to the standard + * .Xr fputs 3 + * function. + */ +extern int StreamPuts(Stream *, char *); -extern char * - StreamGets(Stream *, char *, int); +/** + * Read at most the specified number of characters minus 1 from the + * specified stream and store them at the memory located at the + * specified pointer. This function is analogous to the standard + * .Xr fgets 3 + * function. + */ +extern char * StreamGets(Stream *, char *, int); -extern off_t - StreamSeek(Stream *, off_t, int); +/** + * Set the file position indicator for the specified stream. This + * function is analogous to the standard + * .Xr fseeko + * function. + */ +extern off_t StreamSeek(Stream *, off_t, int); -extern int - StreamEof(Stream *); +/** + * Test the end-of-file indicator for the given stream, returning a + * boolean value indicating whether or not it is set. This is analogous + * to the standard + * .Xr feof 3 + * function. + */ +extern int StreamEof(Stream *); -extern int - StreamError(Stream *); +/** + * Test the stream for an error condition, returning a boolean value + * indicating whether or not one is present. This is analogous to the + * standard + * .Xr ferror 3 + * function. + */ +extern int StreamError(Stream *); -extern void - StreamClearError(Stream *); +/** + * Clear the error condition associated with the given stream, allowing + * future reads or writes to potentially be successful. This functio + * is analogous to the standard + * .Xr clearerr 3 + * function. + */ +extern void StreamClearError(Stream *); -extern int - StreamFlush(Stream *); +/** + * Flush all buffered data using the streams underlying write function. + * This function is analogous to the standard + * .Xr fflush 3 + * function. + */ +extern int StreamFlush(Stream *); -extern ssize_t - StreamCopy(Stream *, Stream *); +/** + * Read all the bytes from the first stream and write them to the + * second stream. This is analogous to + * .Fn IoCopy , + * but it uses the internal buffers of the streams. It is probably + * less efficient than doing a + * .Fn IoCopy + * instead, but it is more convenient. + */ +extern ssize_t StreamCopy(Stream *, Stream *); -extern int - StreamFileno(Stream *); +/** + * Get the file descriptor associated with the given stream, or -1 if + * the stream is not associated with any file descriptor. This function + * is analogous to the standard + * .Xr fileno 3 + * function. + */ +extern int StreamFileno(Stream *); #endif /* TELODENDRIA_STREAM_H */ diff --git a/src/include/Tls.h b/src/include/Tls.h index 6f3651b..c36b574 100644 --- a/src/include/Tls.h +++ b/src/include/Tls.h @@ -24,34 +24,86 @@ #ifndef TELODENDRIA_TLS_H #define TELODENDRIA_TLS_H +/*** + * @Nm Tls + * @Nd Interface to platform-dependent TLS libraries. + * @Dd April 29 2023 + * @Xr Stream Io + * + * .Nm + * provides an interface to platform-dependent TLS libraries. It allows + * Telodendria to support any TLS library with no changes to existing + * code. Support for additional TLS libraries is added by creating a + * new compilation unit that implements all the functions here, with + * the exception of a few, which are noted. + * .Pp + * Currently, Telodendria has support for the following TLS libraries: + * .Bl -bullet -offset indent + * .It + * LibreSSL + * .It + * OpenSSL + * .El + */ + #include #define TLS_LIBRESSL 2 #define TLS_OPENSSL 3 -extern Stream * - TlsClientStream(int, const char *); - -extern Stream * - TlsServerStream(int, const char *, const char *); - -/* - * These are provided by individual TLS implementations. +/** + * Create a new TLS client stream using the given file descriptor and + * the given server hostname. The hostname should be used to verify + * that the server actually is who it says it is. + * .Pp + * This function does not need to be implemented by the individual + * TLS support stubs. */ +extern Stream * TlsClientStream(int, const char *); -extern void * - TlsInitClient(int, const char *); +/** + * Create a new TLS server stream using the given certificate and key + * file, in the format natively supported by the TLS library. + * .Pp + * This function does not need to be implemented by the individual + * TLS support stubs. + */ +extern Stream * TlsServerStream(int, const char *, const char *); -extern void * - TlsInitServer(int, const char *, const char *); +/** + * Initialize a cookie that stores information about the given client + * connection. This cookie will be passed into the other functions + * defined by this API. + */ +extern void * TlsInitClient(int, const char *); -extern ssize_t - TlsRead(void *, void *, size_t); +/** + * Initialize a cookie that stores information about the given + * server connection. This cookie will be passed into the other + * functions defined by this API. + */ +extern void * TlsInitServer(int, const char *, const char *); -extern ssize_t - TlsWrite(void *, void *, size_t); +/** + * Read from a TLS stream, decrypting it and storing the result in the + * specified buffer. This function takes the cookie, buffer, and + * number of decrypted bytes to read into it. See the documentation for + * .Fn IoRead . + */ +extern ssize_t TlsRead(void *, void *, size_t); -extern int - TlsClose(void *); +/** + * Write to a TLS stream, encrypting the buffer. This function takes + * the cookie, buffer, and number of unencrypted bytes to write to + * the stream. See the documentation for + * .Fn IoWrite . + */ +extern ssize_t TlsWrite(void *, void *, size_t); + +/** + * Close the TLS stream, also freeing all memory associated with the + * cookie. + */ +extern int TlsClose(void *); #endif /* TELODENDRIA_TLS_H */ diff --git a/src/include/Uri.h b/src/include/Uri.h index 414c652..4f7cb83 100644 --- a/src/include/Uri.h +++ b/src/include/Uri.h @@ -24,10 +24,28 @@ #ifndef TELODENDRIA_URI_H #define TELODENDRIA_URI_H +/*** + * @Nm Uri + * @Nd Parse a URI. Typically used to parse HTTP(s) URLs. + * @Dd April 29 2023 + * @Xr Http + * + * .Nm + * provides a simple mechanism for parsing URIs. This is an extremely + * basic parser that (ab)uses + * .Xr sscanf 3 + * to parse URIs, so it may not be the most reliable, but it should + * work in most cases and on reasonable URIs that aren't too long, as + * the _MAX definitions are modest. + */ + #define URI_PROTO_MAX 8 #define URI_HOST_MAX 128 #define URI_PATH_MAX 256 +/** + * The parsed URI is stored in this structure. + */ typedef struct Uri { char proto[URI_PROTO_MAX]; @@ -36,10 +54,16 @@ typedef struct Uri unsigned short port; } Uri; -extern Uri * - UriParse(const char *); +/** + * Parse a URI string into the Uri structure as described above, or + * return NULL if there was a parsing error. + */ +extern Uri * UriParse(const char *); -extern void - UriFree(Uri *); +/** + * Free the memory associated with a Uri structure returned by + * .Fn UriParse . + */ +extern void UriFree(Uri *); #endif /* TELODENDRIA_URI_H */ diff --git a/src/include/User.h b/src/include/User.h index f00e336..a82f6d6 100644 --- a/src/include/User.h +++ b/src/include/User.h @@ -181,9 +181,6 @@ extern int UserCheckPassword(User *, char *); */ extern int UserSetPassword(User *, char *); -extern int - UserDeactivate(User *); - /** * Immediately deactivate the given user account such that it can no * longer be used to log in, but the username is still reserved. This @@ -191,6 +188,14 @@ extern int * of a given localpart. The user is logged out; all access tokens are * invalidated. */ +extern int UserDeactivate(User *); + +/** + * Return a boolean value indicating whether or not the user was + * deactivated using + * .Fn UserDeactivate . + * Note that once deactivated, users cannot be reactivated. + */ extern int UserDeactivated(User *); /** diff --git a/tools/bin/man-table b/tools/bin/man-table index 1c03c0c..20330f0 100755 --- a/tools/bin/man-table +++ b/tools/bin/man-table @@ -6,7 +6,7 @@ printf "Man Page" printf "Description" printf "" -find man -type f -name '*.[1-9]' | sort -r | while IFS= read -r file; do +find man build/man -type f -name '*.[1-9]' | sort -r | while IFS= read -r file; do base=$(basename "$file") name=$(echo "$base" | rev | cut -d '.' -f 2- | rev) diff --git a/tools/bin/td b/tools/bin/td index 2e9e87c..bc0603a 100644 --- a/tools/bin/td +++ b/tools/bin/td @@ -123,6 +123,10 @@ recipe_docs() { fi fi done + + if which makewhatis 2>&1 > /dev/null; then + makewhatis "$(pwd)/man" + fi } # Build the source code, and generate the 'build/telodendria' @@ -178,6 +182,8 @@ recipe_build() { if ! intcheck; then exit 1 fi + + recipe_docs } recipe_run() { @@ -239,6 +245,8 @@ recipe_site() { exit 1 fi + recipe_docs + # Set some variables that may be replaced in the files. DATE=$(date) USER_DOCS=$(man-table user) @@ -256,15 +264,15 @@ recipe_site() { done cd - >/dev/null - find man/ -name '*.[1-9]' | while IFS= read -r man; do - dir=$(dirname "$man") + find man/ build/man/ -name '*.[1-9]' | while IFS= read -r man; do + section=$(basename "$man" | rev | cut -d '.' -f 1 | rev) html=$(basename "$man") - mkdir -p "$TELODENDRIA_PUB/$dir/" + mkdir -p "$TELODENDRIA_PUB/man/man$section/" mandoc -Thtml \ -O style=/style.css,man=/man/man%S/%N.%S.html "$man" \ - >"$TELODENDRIA_PUB/$dir/$html.html" - echo "$TELODENDRIA_PUB/$dir/$html.html" + >"$TELODENDRIA_PUB/man/man$section/$html.html" + echo "$TELODENDRIA_PUB/man/man$section/$html.html" done }