thgs/fediscovery

Discovery clients for the Fediverse

v0.3.0 2024-04-15 11:58 UTC

Requires

• php: ^8.2

Requires (Dev)

• phpunit/phpunit: ^11

AGPL-3.0-or-later

• Theo Gotsopoulos

• metadata
• discovery
• webfinger
• fediverse

README

This package provides a set of metadata discovery clients that are used by Fediverse software.

Currently only Webfinger has been implemented, however NodeInfo and Host-Meta are planned to be added.

Features

This library strives to be compliant with the below specifications:

• 7033 - Webfinger
• 7565 - The "acct" URI Scheme
• 3986 - URI (#section-3.2.2 and #section-3.4)
• 2616 - HTTP/1.1 (#section-10.4.1 and #section-10.4.5)
• 6415 - JSON Resource Descriptor (JRD)
• NodeInfo - NodeInfo

and CORS in respect to Webfinger.

Future candidates:

• 8288 - Web linking (obsoletes 5988)
• HostMeta

Installation

Can be installed as a composer dependency

composer require thgs/fediscovery

To use any client you will need create an implementation of HttpClientInterface.

Webfinger Client Usage

$client = new WebfingerClient($httpClientImplementation);

// Then you can query like so:

$result = $client->query('[e-mail]');
$result = $client->queryDefaultHost('[e-mail]');  // need to pass `defaultHost` in WebfingerClient constructor
$result = $client->queryLinksOnly('[e-mail]');        // returns array with JRDLink objects
$result = $client->queryRawUrl('https://phpc.social/.well-known/webfinger?resource=[e-mail]');

The client can be configured by passing arguments in the constructor:

• HttpClientInterface - The HTTP client implementation.
• [defaultHost] - Optionally set a default host to be used with queryDefaultHost and skip host resolution.
• [HostResolver] - Optionally pass a custom implementation of HostResolver.
• [mediaType] - Default: application/jrd+json
• [maxRedirects] - Default: 2 - Control how many redirects will be followed while performing a Webfinger.
• [forceSecure] - Default: true - If turned on, will return an error if a call is attempted over HTTP and only allow HTTPS.
• [forceAcctPrefix] - Default: true - If turned on, when a query is issued without the "acct:" prefix, the prefix will be prepended.
• [cleanPrefixedAt] - Default: true - If turned on, will remove any '@' before the user portion.

Methods:

• query(string $targetUri, string ...$relations): WebfingerResult

Query an account in the form of acct:[e-mail] or [e-mail]. The host will be resolved from the account. Returns a JRD object on success.

• queryLinksOnly(string $targetUri, string ...$relations): WebfingerResult

Shortcut method when you only care about the links. It never deserialises a full JRD. Returns an array of JRDLink on success.

• queryDefaultHost(string $targetUri, string ...$relations): WebfingerResult

Query the configured default host without any host resolution. Returns a JRD object on success.

• queryRawUrl(string $url, array $headers = []): WebfingerResult

Raw query of the given URL without any host resolution or pointing to /.well-known/webfinger. Returns a JRD object on success.

Webfinger Result & errors

All methods return a WebfingerResult object which may contain one of the below:

• JRD object
• Instance of WebfingerError
• array of JRDLink objects

NodeInfo Client Usage

$client = new NodeInfoClient($httpClientImplementation);

// Then you can query like so:

$result = $client->query('phpc.social');

NodeInfo Result & errors

Result will be NodeInfoResult object which may contain one of the below:

• Instance of NodeInfoError
• NodeInfo object

Licence

The whole repository is distributed under the terms of AGPLv3.

Contributions

All contributions are welcome as long as one is ready to comply with the tools and enforced styles and manners of this codebase.