webfinger

package module
Version: v0.0.0-...-824606d Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 16, 2018 License: MIT Imports: 6 Imported by: 0

README

GoDoc

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

View Source
const (
	NoCacheMiddleware     string = "NoCache"
	CorsMiddleware        string = "Cors"
	ContentTypeMiddleware string = "Content-Type"
)

Middleware constant keys

View Source
const WebFingerPath = "/.well-known/webfinger"

WebFingerPath defines the default path of the webfinger handler.

Variables

This section is empty.

Functions

func ErrorFromContext

func ErrorFromContext(ctx context.Context) error

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 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 Rel

type Rel string

Rel allows referencing a subset of the users 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.

func Default

func Default(ur Resolver) *Service

Default creates a new service with the default registered handlers

func (*Service) ServeHTTP

func (s *Service) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*Service) Webfinger

func (s *Service) Webfinger(w http.ResponseWriter, r *http.Request)

Webfinger is the webfinger handler

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL