Document TelodendriaConfig

This commit is contained in:
Jordan Bancino 2022-12-10 23:34:32 +00:00
parent 152d444e32
commit 323dad1f8b
4 changed files with 102 additions and 42 deletions

View file

@ -36,7 +36,7 @@ Due: January 1, 2023
[ ] Matrix
[x] Queue
[ ] Routes
[ ] TelodendriaConfig
[x] TelodendriaConfig
[x] Util
[x] Memory
[x] Db

View file

@ -0,0 +1,95 @@
.Dd $Mdocdate: December 10 2022 $
.Dt TELODENDRIACONFIG 3
.Os Telodendria Project
.Sh NAME
.Nm TelodendriaConfig
.Nd Parse the configuration file into a structure.
.Sh SYNOPSIS
.In TelodendriaConfig.h
.Ft TelodendriaConfig *
.Fn TelodendriaConfigParse "HashMap *" "LogConfig *"
.Ft void
.Fn TelodendriaConfigFree "TelodendriaConfig *"
.Sh DESCRIPTION
.Pp
Validate and maintain the Telodendria server's configuration data. This API
builds on the JSON API to add Telodendria-specific parsing. It takes a
fully-parsed JSON object and converts it into a TelodendriaConfig, which is
much more structured and easier to work with than the JSON. The config
structure is not opaque like many other structures in Telodendria. This is
intentional; defining functions for all of the fields would just add a lot
of unecessary overhead. The structure is defined as follows:
.Bd -literal -offset indent
typedef struct TelodendriaConfig
{
char *serverName;
char *baseUrl;
char *identityServer;
char *uid;
char *gid;
char *dataDir;
unsigned short listenPort;
unsigned int flags;
unsigned int threads;
unsigned int maxConnections;
size_t maxCache;
char *logTimestamp;
int logLevel;
} TelodendriaConfig;
.Ed
.Pp
Since the configuration will live in memory for a long time, it is important
that unused values are freed as soon as possible. Therefore, the Telodendria
structure is not opaque; values are accessed directly, and they can be
freed as the program wishes. Do note that if you're going to free a value, you
should set it to NULL, because
.Fn TelodendriaConfigFree
will unconditionally call
.Fn Free
on all values.
.Pp
The flags variable in this structure is a bit field that contains the OR-ed values
of any of the given flags:
.Bd -literal -offset indent
typedef enum TelodendriaConfigFlag
{
TELODENDRIA_FEDERATION,
TELODENDRIA_REGISTRATION,
TELODENDRIA_LOG_COLOR,
TELODENDRIA_LOG_FILE,
TELODENDRIA_LOG_STDOUT,
TELODENDRIA_LOG_SYSLOG
} TelodendriaConfigFlag;
.Ed
.Pp
Do note that the actual values of these enums are omitted, but they can be
OR-ed together and added to flags.
.Pp
.Fn TelodendriaConfigParse
parses a JSON map, extracting the necessary values, validating them, and then
adding them to a new TelodendriaConfig for future use by the program. All values
are copied, so the JSON hash map can be safely freed if this function
succeeds. It takes a working log configuration so that messages can be written
to the log as the parsing progresses, to warn users about default values and
report errors, for example.
.Pp
.Fn TelodendriaConfigFree
frees all of the memory allocated for the given configuration. This function
unconditionally calls
.Fn Free
on all items in the structure, so make sure that items that were already freed
are NULL.
.Sh RETURN VALUES
.Pp
.Fn TelodendriaConfigParse
returns a TelodendriaConfig that is completely independent of the passed
configuration hash map, or NULL if one or more required values is missing, or
there was some other error while parsing the configuration.
.Sh SEE ALSO
.Xr Json 3

View file

@ -241,6 +241,12 @@ A feature-complete API for reading and writing JSON.
An extension to the Json API that implements Matrix's canonical JSON.
</td>
</tr>
<tr>
<td><a href="man/man3/TelodendriaConfig.3.html">TelodendriaConfig(3)</a></td>
<td>
Parse the configuration file into a structure.
</td>
</tr>
</table>
<h2 id="resources">Resources</h2>
<ul>

View file

@ -22,12 +22,6 @@
* SOFTWARE.
*/
/*
* TelodendriaConfig.h: Validate and maintain the Telodendria server's
* configuration data. This API builds on the Config API to add
* Telodendria-specific parsing. It takes a fully parsed Config, and
* converts it into a TelodendriaConfig, which is more structured.
*/
#ifndef TELODENDRIA_TELODENDRIACONFIG_H
#define TELODENDRIA_TELODENDRIACONFIG_H
@ -44,15 +38,6 @@ typedef enum TelodendriaConfigFlag
TELODENDRIA_LOG_SYSLOG = (1 << 5)
} TelodendriaConfigFlag;
/*
* Since this configuration will live in memory for a long time, it is
* important that unused values are freed as soon as possible. Therefore,
* the TelodendriaConfig structure is not opaque; values are accessed
* directly, and they can be freed as the program wishes.
*
* NOTE: If you're going to free a value, make sure you set the pointer
* to NULL. TelodendriaConfigFree() will call free() on all values.
*/
typedef struct TelodendriaConfig
{
char *serverName;
@ -74,35 +59,9 @@ typedef struct TelodendriaConfig
int logLevel;
} TelodendriaConfig;
/*
* Parse a Config map, extracting the necessary values, validating them,
* and then adding them to a new TelodendriaConfig for future use by the
* program. All values are copied, so the Config hash map can be safely
* freed if this function succeeds.
*
* Params:
* (HashMap *) A hash map from ConfigParse(). This should be a map of
* ConfigDirectives.
* (LogConfig *) A working log configuration. Messages are written to
* this log as the parsing progresses, and this log is
* copied into the resulting TelodendriaConfig. It is
* also potentially modified by the configuration file's
* "log" block.
*
* Return: A TelodendriaConfig that is completely independent of the passed
* configuration hash map, or NULL if one or more required values is missing.
*/
extern TelodendriaConfig *
TelodendriaConfigParse(HashMap *, LogConfig *);
/*
* Free all of the memory allocated to the given configuration. This
* function unconditionally calls free() on all items in the structure,
* so make sure items that were already freed are NULL.
*
* Params:
* (TelodendriaConfig *) The configuration to free all the values for.
*/
extern void
TelodendriaConfigFree(TelodendriaConfig *);