micropub

Documentation

Index

• Constants
• Variables
• func NewHandler(impl Implementation, options ...Option) http.Handler
• func NewMediaHandler(mediaUploader MediaUploader, scopeChecker ScopeChecker, options ...MediaOption) http.Handler
• type Action
• type Channel
• type Configuration
• type Implementation
• type MediaConfiguration
• type MediaOption
  • func WithMaxMediaSize(size int64) MediaOption
  • func WithMaxMemory(size int64) MediaOption
• type MediaUploader
• type Option
  • func WithGetCategories(getCategories func() []string) Option
  • func WithGetChannels(getChannels func() []Channel) Option
  • func WithGetPostTypes(getPostTypes func() []PostType) Option
  • func WithGetSyndicateTo(getSyndicateTo func() []Syndication) Option
  • func WithGetVisibility(getVisibility func() []string) Option
  • func WithMediaEndpoint(endpoint string) Option
• type PostType
• type Request
  • func ParseRequest(r *http.Request) (*Request, error)
• type RequestUpdate
• type ScopeChecker
• type Syndication

Constants

const (
	// DefaultMaxMediaSize is the default max media size, which is 20 MiB.
	DefaultMaxMediaSize = 20 << 20
)

Variables

var (
	ErrNotFound       = errors.New("not found")
	ErrBadRequest     = errors.New("invalid request")
	ErrNotImplemented = errors.New("not implemented")
)

var (
	ErrNoFormUpdate   = errors.New("micropub update actions require using the JSON syntax")
	ErrNoURL          = errors.New("micropub actions require a URL property")
	ErrNoData         = errors.New("no micropub data was found in the request")
	ErrNoActionCreate = errors.New("cannot specify an action when creating a post")
	ErrMultipleTypes  = errors.New("type must have a single value")
)

Functions

func NewHandler

func NewHandler(impl Implementation, options ...Option) http.Handler

NewHandler creates a new Micropub http.Handler conforming to the specification. It uses the given [RouterImplementation] and [Option]s to handle the requests.

The returned handler can be mounted under the path for a Micropub server. The following routes are processed (assuming is mounted under /micropub):

• GET /micropub?q=source
• GET /micropub?q=config
• GET /micropub?q=syndicate-to
• GET /micropub?q=category
• GET /micropub?q=channel
• POST /micropub (form-encoded): create, delete, undelete
• POST /micropub (json): create, update, delete, undelete

func NewMediaHandler

func NewMediaHandler(mediaUploader MediaUploader, scopeChecker ScopeChecker, options ...MediaOption) http.Handler

NewMediaHandler creates a Micropub media endpoint handler with the given configuration.

Types

type Action

type Action string

Action represents a Micropub action.

const (
	ActionCreate   Action = "create"
	ActionUpdate   Action = "update"
	ActionDelete   Action = "delete"
	ActionUndelete Action = "undelete"
)

type Channel

type Channel = uidAndName

Channel represents a channel.

type Configuration

type Configuration struct {
	MediaEndpoint  string
	GetSyndicateTo func() []Syndication
	GetChannels    func() []Channel
	GetCategories  func() []string
	GetPostTypes   func() []PostType
	GetVisibility  func() []string
}

Configuration is the configuration of a [Router]. Use the different Option to customize your endpoint.

type Implementation

type Implementation interface {
	// HasScope returns whether or not the request is authorized for a certain scope.
	HasScope(r *http.Request, scope string) bool

	// Source returns the Microformats source of a certain URL.
	Source(url string) (map[string]any, error)

	// Source all returns the Microformats source for a [limit] amount of posts,
	// offset by the given [offset]. Used to implement [post list]. Limit will be
	// -1 by default, and offset 0.
	//
	// [post list]: https://indieweb.org/Micropub-extensions#Query_for_Post_List
	SourceMany(limit, offset int) ([]map[string]any, error)

	// Create makes a create request according to the given [Request].
	// Must return the location (e.g., URL) of the created post.
	Create(req *Request) (string, error)

	// Update makes an update request according to the given [Request].
	// Must return the location (e.g., URL) of the update post.
	Update(req *Request) (string, error)

	// Delete deletes the post at the given URL.
	Delete(url string) error

	// Undelete reverts a deletion of the post at the given URL.
	Undelete(url string) error
}

Implementation is the backend implementation necessary to run a Micropub server with [Router].

You must implement [Implementation.HasScope]. The remaining functions can return ErrNotImplemented if you don't support the feature.

You can also return ErrNotFound and ErrBadRequest and the status code, as well as JSON error, will be set accordingly.

type MediaConfiguration

type MediaConfiguration struct {
	MaxMediaSize int64
	MaxMemory    int64
}

MediaConfiguration is the configuration for a media handler.

type MediaOption

type MediaOption func(*MediaConfiguration)

MediaOption is an option that configures MediaConfiguration.

func WithMaxMediaSize

func WithMaxMediaSize(size int64) MediaOption

WithMaxMediaSize configures the maximum size of media uploads, in bytes. By default it is 20 MiB.

func WithMaxMemory

func WithMaxMemory(size int64) MediaOption

WithMaxMemory configures how much of the uploads are kept in memory. See http.Request.ParseMultipartForm for more details. By default it is 0, meaning that the upload is kept in temporary files.

type MediaUploader

type MediaUploader func(file multipart.File, header *multipart.FileHeader) (string, error)

MediaUploader is the media upload function. Must return the location (e.g., URL) of the uploaded file.

type Option

type Option func(*Configuration)

func WithGetCategories

func WithGetCategories(getCategories func() []string) Option

WithGetCategories configures the getter for the categories. This allows for dynamic categories. Return an empty slice if there are no categories.

func WithGetChannels

func WithGetChannels(getChannels func() []Channel) Option

WithGetChannels configures the getter for channels. This allows for dynamic channels. Return an empty slice if there are no channels.

func WithGetPostTypes

func WithGetPostTypes(getPostTypes func() []PostType) Option

WithGetPostTypes configures the getter for the allowed post types. This allows for dynamic post types. Return an empty slice if you don't want it to be set in the configuration.

func WithGetSyndicateTo

func WithGetSyndicateTo(getSyndicateTo func() []Syndication) Option

WithGetSyndicateTo configures the getter for syndication targets. This allows for dynamic syndication targets. Return an empty slice if there are no targets.

func WithGetVisibility

func WithGetVisibility(getVisibility func() []string) Option

WithGetVisibility configures the getter for supported visibility. Return an empty slice if there are no channels.

func WithMediaEndpoint

func WithMediaEndpoint(endpoint string) Option

WithMediaEndpoint configures the URL of the media endpoint. This is used when a Micropub client asks for the configuration of the endpoint. If this is not set, a client won't be able to recognize the endpoint.

type PostType

type PostType struct {
	Type       string   `json:"type"`
	Name       string   `json:"name"`
	Properties []string `json:"properties,omitempty"`
	Required   []string `json:"required-properties,omitempty"`
}

PostType is used to provide information regarding the server's supported vocabulary.

type Request

type Request struct {
	Action     Action
	URL        string
	Type       string
	Properties map[string][]any
	Commands   map[string][]any
	Updates    RequestUpdate
}

Request describes a Micropub request.

func ParseRequest

func ParseRequest(r *http.Request) (*Request, error)

ParseRequest parses a Micropub POST http.Request into a Request object. Supports both JSON and form-encoded requests.

type RequestUpdate

type RequestUpdate struct {
	Replace map[string][]any
	Add     map[string][]any
	Delete  any
}

type ScopeChecker

type ScopeChecker func(r *http.Request, scope string) bool

ScopeChecker is a function that checks if the user has the required scope to handle the given request.

type Syndication

type Syndication = uidAndName

Syndication represents a syndication target.