Add README

This commit is contained in:
Karcsesz 2024-02-14 23:42:57 +01:00
parent cbaaf18cf5
commit 8c03ac337d

65
README.md Normal file
View file

@ -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.