webfinger

Documentation

Index

• func AccountURL(s string) (*url.URL, error)
• type Config
  • func NewConfig() *Config
  • func (c *Config) WebFinger(u *url.URL) (*Result, error)
• type Link
• type Result
• Bugs

Functions

func AccountURL

func AccountURL(s string) (*url.URL, error)

AccountURL parses common webfinger URL representations. This should be used for user-submitted URLs only. For programmatically determined URLs, use url.Parse directly.

Supported formats:

https://domain/path
user@domain
@user@domain
acct:user@domain

Types

type Config

type Config struct {
	// LookupCachedDomain is a best-effort cache lookup for domains stored
	// by StoreDomainInCache.
	//
	// The boolean return value determines whether the cached result is
	// used. Returning an empty string and true signals a cached
	// negative result.
	LookupCachedDomain func(domain string) (webDomain string, ok bool)
	// StoreDomainInCache is a best-effort cache storage function.
	//
	// If the domain is already present as an unexpired entry in the cache,
	// it is up to the implementation whether the existing or new entry
	// should be cached when this function returns.
	//
	// An empty webDomain signals that this is a negative result.
	StoreDomainInCache func(domain, webDomain string, expireAfter time.Duration)
	// ModifyRequest is called before a *http.Request is sent.
	//
	// Suggested uses include setting headers such as User-Agent and adding
	// HTTP signatures.
	ModifyRequest func(req *http.Request) error

	// Context for HTTP requests. Defaults to context.Background().
	BaseContext context.Context

	// Client to use for HTTP requests. Defaults to http.DefaultClient.
	Client *http.Client

	// Timeout per host-meta request. Set to 0 to disable timeout.
	HostTimeout time.Duration
	// Timeout per webfinger request. Set to 0 to disable timeout.
	WebTimeout time.Duration

	// Number of domain names other than the account's subject domain and
	// the domain that handles webfinger requests that may be claimed as
	// webfinger aliases. Additional domains used in aliases will be
	// discarded as unverified.
	MaxExtraDomains int

	// Cache durations for host-meta. Set to 0 to disable caching.
	CacheSuccess  time.Duration // successfully determined domain
	CacheError    time.Duration // failed to access host-meta
	CacheNegative time.Duration // does not exist or lacks webfinger url
	// contains filtered or unexported fields
}

Config holds all the configurable behavior of the webfinger package.

All functions held in fields of this structure must be concurrency-safe. After calling a method on *Config, it is unsafe to modify the fields. Function fields that are left nil act as no-ops.

Config should be reused where possible, as it attempts to prevent duplicate requests. All methods on Config are concurrency-safe.

func NewConfig

func NewConfig() *Config

NewConfig returns a *Config with some reasonable default settings.

func (*Config) WebFinger

func (c *Config) WebFinger(u *url.URL) (*Result, error)

WebFinger queries the webfinger endpoint for the given account URL. The Subject and Aliases fields of the returned *Result are verified, meaning the same webfinger endpoint would be used for all of them.

An unverified Subject results in an error, and unverified Aliases are dropped.

One webfinger request is performed, along with up to 3 + MaxExtraDomains host-meta requests. The three default allowed host-meta requests are the provided URL's domain, the domain specified as the webfinger URL for that domain, and the domain of the claimed subject.

A maximum of one host-meta request will be performed for each domain, even if there is no cache defined in the *Config.

type Link

type Link struct {
	Rel      string `json:"rel"`
	Type     string `json:"type,omitempty"`
	Href     string `json:"href,omitempty"`
	Template string `json:"template,omitempty"`
}

Link is a related URL.

type Result

type Result struct {
	// Subject is the main (canonical) URL of the resource.
	Subject string `json:"subject"`
	// Aliases are additional URLs where the resource can be accessed.
	Aliases []string `json:"aliases"`

	// Links are unverified URL claims with semantics based on Rel.
	Links []Link `json:"links"`
}

Result is a filtered response to a webfinger request for a resource.

Notes

Bugs

• this assumes Mastodon URL structures (should be fine for now)

• this assumes Mastodon URL structures (should be fine for now)