rossabaker/kbbl
1
3
Fork 0
Code Issues Pull requests Releases 1 Activity
A Webmention implementation in Rust
142 commits 2 branches 1 tag 394 KiB
  • Rust 80.2%
  • Nix 14.4%
  • HTML 5.4%
Find a file
Ross A. Baker fdba5fdac2
 Fix typo in flake description
2025-12-30 23:51:21 -05:00
crates I'm tired of arguing with Clippy about that _guard 2025-12-30 15:19:17 -05:00
LICENSES Add a Nix flake with a Rust devshell 2025-12-01 22:19:17 -05:00
migrations Add 'U' state, making (source, target) unique 2025-12-22 21:09:42 -05:00
nix Parameterize URL into KBBL_URL environment 2025-12-17 17:11:43 -05:00
.envrc Add a direnv config to use the default devshell 2025-12-01 22:19:17 -05:00
.gitignore Ignore Nix result symlink 2025-12-01 22:29:19 -05:00
Cargo.lock Update Cargo.lock 2025-12-26 23:05:43 -05:00
Cargo.lock.license Initialize a Cargo project 2025-12-01 22:19:17 -05:00
Cargo.toml Look for authorization_endpoint in <link> of body as well 2025-12-16 20:50:39 -05:00
CHANGELOG.org Date the release 2025-12-05 21:45:47 -05:00
flake.lock flake.lock: Update 2025-12-28 18:40:46 -05:00
flake.lock.license Add a Nix flake with a Rust devshell 2025-12-01 22:19:17 -05:00
flake.nix Fix typo in flake description 2025-12-30 23:51:21 -05:00
README.org Add 'U' state, making (source, target) unique 2025-12-22 21:09:42 -05:00

README.org

KBBL

KBBL will be a Webmention implementation in Rust. It is named after the radio station in The Simpsons.

No sports, no rock, no information; for mindless chatter, we're your station!

What does it do

kbbl-cli

The kbbl-cli crate provides the kbbl command line interface. It is a fully stateless application.

Sends web mentions 

kbbl send --source https://me.example.com/mention --target https://them.example.net/mentionable

The webmention endpoint is discovered by fetching the target. If found, a web mention is sent to that endpoint from target to source.

Success is reflected in the exit code of the process.

Verifies web mentions 

kbbl receive --source https://them.example.com/mention --target https://me.example.com/mentionable

The webmention is checked to ensure that the source does not equal the target, and that both source and target are either http or https URIs.

The source is then fetched and inspected for a link back to target. Currently supported are:

  • a[href]
  • img[src]
  • video[src]
  • audio[src]

Success is reflected in the exit code of the process.

kbbl-server

kbbl-server is a stateful, opinionated HTTP server for managing your webmentions.

SQLite storage

The server depends on a SQLite data store. Create it thusly:

  cargo sqlx database setup -D sqlite:kbbl.db

To upgrade, migrations are run similarly:

  cargo sqlx migrations run -D sqlite:kbbl.db

Authentication

kbbl-server supports IndieAuth. IndieAuth only authenticates. You need to specify who is allowed to administer your server. This is currently done directly against the database:

  INSERT INTO admins (uri) VALUES ('https://me.example.com/');

In the debug profile, the user https://me.test is be automatically logged in if KBBL_ENABLE_TEST_USER is set to true:

  KBBL_ENABLE_TEST_USER=true cargo run -p kbbl-server

Running the server 

  cargo run -p kbbl-server

The server defaults to port https://localhost:21421/. You can go to /login or /admin.

Receiving webmentions

Webmentions are received at /api/v1/webmention. To make kbbl-server discoverable from the pages you want mentioned, add a Link header. Assuming kbbl-server is hosted at webmention.example.com:

  Link: <https://webmention.example.com/api/v1/webmention>; rel="webmention"

Alternatively, a <link> tag may be added to the <head> on your pages:

  <link rel="webmention" href="https://webmention.example.com/api/v1/webmention">

Webmention states

Webmentions are stored in one of the following states:

Abbrev Name Meaning Terminal
P Pending Initial state. Webmention is awaiting verification. No
R Running Automated verification is in progress. No
V Verified Webmention source was fetched, successful, and mentions target. No
G Gone Webmention source returned 410 Gone on verification, representing a deletion. Yes
F Failed Webmention source failed to mention target. No
E Error Error fetching webmention source for validation. No
A Approved Webmention was approved by an admin and ready to display. Yes
D Declined Webmention was declined by an admin. Yes
U Updating A previously approved webmention has been resubmitted but not verified. No

Admin

All administrative activity happens in /admin.

Pending webmentions

Each received webmention is put into the pending state. All webmentions in a non-terminal state may be approved or declined from the admin page. Approved webmentions will be made accessible for display by future endpoints. Declined webmentions are soft deleted.

Verification of the webmention is not yet performed by the server. All state changes are manual.

License

KBBL is licensed under the Mozilla Public License 2.0 (MPL-2.0).