README
¶
go-webfinger
go-webfinger is a golang webfinger server implementation. See v1.0 for the latest stable version, and our Code.as repo for the Write.as-specific implementation.
Past v1.0, this fork was made especially for federation support on Write.as, which includes users across write.as, *.writeas.com, and custom domains we host. The master branch contains changes specific to our implementation, and will change without notification.
Usage
webfinger.Service is implemented as a net/http handler, which means
usage is simply registering the object with your http service.
Using the webfinger service as the main ServeHTTP:
myResolver = ...
wf := webfinger.Default(myResolver{})
wf.NotFoundHandler = // the rest of your app
http.ListenAndService(":8080", wf)
Using the webfinger service as a route on an existing HTTP router:
myResolver = ...
wf := webfinger.Default(myResolver{})
http.Handle(webfinger.WebFingerPath, http.HandlerFunc(wf.Webfinger))
http.ListenAndService(":8080", nil)
Defaults
The webfinger service is installed with a few defaults. Some of these defaults ensure we stick closely to the webfinger specification (tls-only, CORS, Content-Type) and other defaults are simply useful for development (no-cache)
The full list of defaults can be found in the godoc for webfinger.Service. They are exposed
as public variables which can be overriden.
PreHandlers are the list of preflight HTTP handlers to run. You can add your own via wf.PreHandlers["my-custom-name"] = ..., however,
execution order is not guaranteed.
TLS-Only
Handler which routes to the TLS version of the page. Disable via wf.NoTLSHandler = nil.
No-Cache
A PreFlight handler which sets no-cache headers on anything under /.well-known/webfinger. Disable or override via wf.PreHandlers[webfinger.NoCacheMiddleware]
Content Type as application/jrd+json
A PreFlight handler which sets the Content-Type to application/jrd+json. Disable or override via wf.PreHandlers[webfinger.ContentTypeMiddleware].
CORS
A PreFlight handler which adds the CORS headers. Disable or override via wf.PreHandlers[webfinger.CorsMiddleware].
Documentation
¶
Overview ¶
Package webfinger is a server implementation of the webfinger specification. This is a general-case package which provides the HTTP handlers and interfaces for adding webfinger support for your system and resources.
The simplest way to use this is to call webfinger.Default() and then register the object as an HTTP handler:
myResolver = ...
wf := webfinger.Default(myResolver{})
wf.NotFoundHandler = // the rest of your app
http.ListenAndService(":8080", wf)
However, you can also register the specific webfinger handler to a path. This should work on any router that supports net/http.
myResolver = ...
wf := webfinger.Default(myResolver{})
http.Handle(webfinger.WebFingerPath, http.HandlerFunc(wf.Webfinger))
http.ListenAndService(":8080", nil)
In either case, the handlers attached to the webfinger service get invoked as needed.
Index ¶
Constants ¶
const ( NoCacheMiddleware string = "NoCache" CorsMiddleware string = "Cors" ContentTypeMiddleware string = "Content-Type" )
Middleware constant keys
const WebFingerPath = "/.well-known/webfinger"
WebFingerPath defines the default path of the webfinger handler.
Variables ¶
This section is empty.
Functions ¶
func ErrorFromContext ¶
ErrorFromContext gets the error from the context
Types ¶
type ErrorKeyType ¶
type ErrorKeyType int
ErrorKeyType is the type for the context error key
var ErrorKey ErrorKeyType
ErrorKey is the key for the context error
type Link ¶
type Link struct {
HRef string `json:"href"`
Type string `json:"type,omitempty"`
Rel string `json:"rel"`
Properties map[string]*string `json:"properties,omitempty"`
Titles map[string]string `json:"titles,omitempty"`
}
A Link is a series of user details
type Resolver ¶
type Resolver interface {
// FindUser finds the user given the username and hostname.
FindUser(username string, hostname, requestHost string, r []Rel) (*Resource, error)
// DummyUser allows us to return a dummy user to avoid user-enumeration via webfinger 404s. This
// can be done in the webfinger code itself but then it would be obvious which users are real
// and which are not real via differences in how the implementation works vs how
// the general webfinger code works. This does not match the webfinger specification
// but is an extra precaution. Returning a NotFound error here will
// keep the webfinger 404 behavior.
DummyUser(username string, hostname string, r []Rel) (*Resource, error)
// IsNotFoundError returns true if the given error is a not found error.
IsNotFoundError(err error) bool
}
The Resolver is how the webfinger service looks up a user or resource. The resolver must be provided by the developer using this package, as each webfinger service may be exposing a different set or users or resources or services.
type Resource ¶
type Resource struct {
Subject string `json:"subject,omitempty"`
Aliases []string `json:"aliases,omitempty"`
Properties map[string]string `json:"properties,omitempty"`
Links []Link `json:"links"`
}
A Resource is the top-level JRD resource object.
type Service ¶
type Service struct {
// PreHandlers are invoked at the start of each HTTP method, used to
// setup things like CORS, caching, etc. You can delete or replace
// a handler by setting service.PreHandlers[name] = nil
PreHandlers map[string]http.Handler
// NotFoundHandler is the handler to invoke when a URL is not matched. It does NOT
// handle the case of a non-existing users unless your Resolver.DummyUser returns
// an error that matches Resolver.IsNotFoundError(err) == true.
NotFoundHandler http.Handler
// MethodNotSupportedHandler is the handler invoked when an unsupported
// method is called on the webfinger HTTP service.
MethodNotSupportedHandler http.Handler
// MalformedRequestHandler is the handler invoked if the request routes
// but is malformed in some way. The default behavior is to return 400 BadRequest,
// per the webfinger specification
MalformedRequestHandler http.Handler
// NoTLSHandler is the handler invoked if the request is not
// a TLS request. The default behavior is to redirect to the TLS
// version of the URL, per the webfinger specification. Setting
// this to nil will allow nonTLS connections, but that is not advised.
NoTLSHandler http.Handler
// ErrorHandler is the handler invoked when an error is called. The request
// context contains the error in the webfinger.ErrorKey and can be fetched
// via webfinger.ErrorFromContext(ctx)
ErrorHandler http.Handler
// Resolver is the interface for resolving user details
Resolver Resolver
}
Service is the webfinger service containing the required HTTP handlers and defaults for webfinger implementations.
Source Files