https://github.com/joshka/webfinger-rs
A rust crate implementing the WebFinger protocol (RFC 7033)
https://github.com/joshka/webfinger-rs
webfinger
Last synced: 7 months ago
JSON representation
A rust crate implementing the WebFinger protocol (RFC 7033)
- Host: GitHub
- URL: https://github.com/joshka/webfinger-rs
- Owner: joshka
- License: apache-2.0
- Created: 2024-09-29T18:11:14.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-04T21:11:25.000Z (7 months ago)
- Last Synced: 2025-03-16T18:44:20.438Z (7 months ago)
- Topics: webfinger
- Language: Rust
- Homepage: https://crates.io/crates/webfinger-rs
- Size: 198 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE-APACHE
- Security: SECURITY.md
Awesome Lists containing this project
README
# Webfinger-rs
[![Crates.io badge]][crate]
[![License badge]][license]
[![Docs.rs badge]][docs]
[![Deps.rs badge]][dependencies]
`webfinger-rs` is a Rust library for handling WebFinger protocol defined by [RFC 7033].
WebFinger is is used to discover information about people or other entities on the internet.
The motivation of this library is to provide a transport-agnostic implementation of the
WebFinger protocol for client and server-side application which can be used with different HTTP
libraries such as [Axum], and [Reqwest]. Additionally, the other available crates for WebFinger
are either not actively maintained and have a license that is incompatible with incorporating
the crate into other projects as a library (GPL-3.0).
[RFC 7033]: https://www.rfc-editor.org/rfc/rfc7033.html
[Axum]: https://crates.io/crates/axum
[Reqwest]: https://crates.io/crates/reqwest
## Usage
To use this library, add it to your `Cargo.toml`:
```shell
cargo add webfinger-rs
```
The library also has a related CLI tool, [`webfinger-cli`], which can be installed with:
```shell
cargo install webfinger-cli
webfinger acct:carol@example.com --rel http://webfinger.net/rel/avatar
```
## Client Example
The following example connects to the WebFinger server at `example.com` and requests the profile
page for the user `carol@example.com`. It requires the `reqwest` feature to be enabled. This
example is also available in the repository at:
.
```rust
use webfinger_rs::WebFingerRequest;
#[tokio::main]
async fn main() -> Result<(), Box> {
let request = WebFingerRequest::builder("acct:carol@example.com")?
.host("example.com")
.rel("http://webfinger.net/rel/profile-page")
.build();
let response = request.execute_reqwest().await?;
dbg!(response);
Ok(())
}
```
## Server Example
The following example is an Axum handler that responds to WebFinger requests. It requires the
`axum` feature to be enabled. This example is also available in the repository at:
.
```rust
use axum::response::Result as AxumResult;
use webfinger_rs::{Link, Rel, WebFingerRequest, WebFingerResponse};
async fn webfinger(request: WebFingerRequest) -> AxumResult {
let subject = request.resource.to_string();
if subject != "acct:carol@example.com" {
Err((http::StatusCode::NOT_FOUND, "Not Found"))?;
}
let rel = Rel::new("http://webfinger.net/rel/profile-page");
let response = if request.rels.is_empty() || request.rels.contains(&rel) {
let link = Link::builder(rel).href(format!("https://example.com/profile/{subject}"));
WebFingerResponse::builder(subject).link(link).build()
} else {
WebFingerResponse::builder(subject).build()
};
Ok(response)
}
```
## Running the examples
To run the examples, you can use the following commands:
```shell
cargo run --example actix --features actix
cargo run --example axum --features axum
```
This will start a server on `https://localhost:3000` that responds to WebFinger requests for a
single user, `carol@localhost`. Use [`webfinger-cli`] tool to query these servers. The servers
create self-signed certificates for `localhost`, which can be ignored with the `--insecure`
flag.
```shell
cargo install webfinger-cli
webfinger acct:carol@localhost localhost:3000 --insecure --rel http://webfinger.net/rel/profile-page
```
[`webfinger-cli`]: https://crates.io/crates/webfinger-cli
## Features / TODO list
- [x] Client side types
- [x] Reqwest interaction
- [x] Server side types
- [x] Axum integration
- [x] Actix integration
## Stability
This library is in early days and will have semver breaking changes in the 0.0.x releases. Once
0.1.0 is released, semver breaking changes will bump the minor version.
## License
Copyright (c) 2024 Josh McKinney
This project is licensed under either of:
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or
)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or ) at your
option.
## MSRV
This library is tested on the latest stable release of Rust. The minimum supported version is the
previous stable release. The library rust version will only be updated when necessary. The library
may work on older versions of Rust, but it is not guaranteed.
## Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the
work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
additional terms or conditions.
See [CONTRIBUTING.md](CONTRIBUTING.md).
[Crates.io badge]: https://img.shields.io/crates/v/webfinger-rs?logo=rust&style=for-the-badge
[License badge]: https://img.shields.io/crates/l/webfinger-rs?style=for-the-badge
[Docs.rs badge]: https://img.shields.io/docsrs/webfinger-rs?logo=rust&style=for-the-badge
[Deps.rs badge]: https://deps.rs/repo/github/joshka/webfinger-rs/status.svg?style=for-the-badge
[crate]: https://crates.io/crates/webfinger-rs
[license]: ./LICENSE-MIT
[docs]: https://docs.rs/webfinger-rs/
[dependencies]: https://deps.rs/repo/github/joshka/webfinger-rs