From 8c03ac337d6d1d3b41f5cb39d4fab325b9fbb63e Mon Sep 17 00:00:00 2001 From: Karcsesz Date: Wed, 14 Feb 2024 23:42:57 +0100 Subject: [PATCH] Add README --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..0511500 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# Fingerlink +General purpose WebFinger daemon and utilities for managing its served resources written in Rust. +## Basic usage +The program is split into two halves: the server daemon and the editing tools. + +There are lots of command line parameters built in, so always check the subcommand's +help page with `fingerlink help [subcommand]` before using. + +Every command that can alter the database defaults to dry-run mode where the actual database +isn't altered. To actually save the result of a command, supply the `--save` flag. The program +also always keeps one backup of the previous database state in case something goes wrong during +writing. The editing processes can also try to reload the running server process when +the `--reload-server` flag is supplied. +## Subcommands +### `serve` +Starts serving the database. By default, it binds to 127.0.0.1:8080, but these values +can be changed by using the `--bind-ip` and `--bind-port` parameters. + +The server keeps a PID file around to enable the optional auto-refresh functionality of +the editing tools and to prevent accidentally running multiple instances of the server +at once. + +### `fetch` +The simplest way to get new records into the database. By supplying a list of +Fediverse-compatible handles, their resource data can be quickly and easily imported +into the database. + +The command tries to prevent multiple resources from taking the same query strings, +and to help with this, there are multiple implemented strategies to handle collisions. + - `terminate` simply stops the import process if a collision is detected. The resources + processed up to the collision are still inserted. + - `skip` skips over every resource that would collide with another resource already + in the database + - `overwrite-single-skip-multiple` overwrites the old resource with the new one, but only + if there's just a single already saved resource that the new resource will collide with. + Otherwise, it skips. This is the default, as it's the most useful for updating old records. + - `overwrite-multiple` overwrites the old resource or resources that the new record collides + with. Can be highly destructive, be careful! + +In case you want to batch-import handles from a file, you can use the `--handles-are-files` flag. +When it's enabled, the command opens the provided handles as files and reads their contents. +One line, one query. + +It can be very useful to replace the old domain in the `subject` field with the one that the +service will run on. In this case you can supply the `--new-domain` parameter. It runs a very +simple process +1. Takes the `subject` field of the returned resource and cuts off everything after the last @ sign. +2. Appends the string provided with the `--new-domain` parameter. +3. Puts it in the `subject` field instead of the old subject +4. Appends the old subject to the `aliases` array + +### `query` +A simple command to get the response JSON to a query without `curl`. It pretty-prints the JSON. + +### `editor` +Uses the editor defined in `$EDITOR` (or `vi` if the environment variable isn't set) to edit +the JSON record returned to the provided query. Like every editor command, it runs in dry-run +mode and requires the `--save` flag to be present to actually modify the database. + +If the `--create` flag is present, then if the query doesn't return a resource, it creates a +new blank resource to fill out and insert into the database. + +### `init` +Creates a new blank database file. If one is already present, it requires the `--force` flag +to be present otherwise it refuses to delete the database. \ No newline at end of file