README
¶
🎺 toot-echo
Echo Adapter for the toot Mastodon API
Toot-echo connects the toot library to the echo router. This makes it easy for you to Mastodon-ize your Go/echo application.
api.PostStatus = func(authorization model.Authorization, values txn.PostStatus) (object.Status, error) {
// Do the thing that:
// 1) creates a new `status`
// 2) writes it to the database
// 3) returns the value to the caller
}
// Once your handlers are defined, connect Toot to your router like this:
e := echo.New()
tootecho.Register(e, api)
Routers
Currently, toot-echo is the only router adapter I have created for Toot. It should, however, be a simple project to write adapters for other routers. If you'd like to use Toot with a different router, please get in touch and let's work together.
Project Status (Alpha)
This project is still in early testing, as I continue filling out the Mastodon support in Emissary. Interfaces may change in the future if I run into trouble making things work with this reference implementation.
However, at this point, feedback from other developers will be immensely helpful in making Toot a useful tool for the Go community. Please feel free to open issues, or submit pull requests. We're all in this together! 🎺
Documentation
¶
Overview ¶
Package tootecho serves a Mastodon API on an Echo web server.
Fill in the handlers of a toot.API and hand it to Register, which walks every endpoint the toot library defines and adds a route for each handler that is present:
api := toot.New(myAuthorizer) api.GetAccount = myGetAccountHandler tootecho.Register(e, api)
A nil handler is skipped rather than registered, so an API that implements ten endpoints serves ten routes and 404s the rest. Middleware passed to Register runs on every route it adds.
Each route wraps its handler in the same three steps: authorize the request and check its required OAuth scope, bind the request into the handler's input struct from the txn package, and marshal whatever the handler returns as JSON.
What the host application still owns ¶
- Error rendering. Handlers report failure by returning a derp error, and this package passes it up to Echo unchanged. Echo's default handler renders any error it does not recognize as a 500, so install a derp-aware HTTPErrorHandler to get real status codes -- 401 for a rejected token, 404 for a missing record, and so on.
- Trusting the proxy. The WithHost middleware prefers the X-Forwarded-Host header over the request's own Host, because a Mastodon API has to report the public hostname of the instance. That header is caller-supplied: run this behind a proxy that overwrites it, or a client can choose the hostname that appears in the responses it receives.
Every response carries "Access-Control-Allow-Origin: *", matching Mastodon, and safe here because authorization rides on a Bearer token rather than on a cookie.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Register ¶
func Register[AuthToken toot.ScopesGetter](e *echo.Echo, api toot.API[AuthToken], middleware ...echo.MiddlewareFunc)
Register adds a route to the Echo server for every handler that the API defines. A handler left nil is skipped, so an incomplete API registers only what it implements. Any middleware passed here runs on each registered route, after the built-in WithHost.
Handlers report failure by returning a derp error, which Echo's default error handler renders as a 500. Install a derp-aware HTTPErrorHandler on the server to get the intended status codes.
func WithHost ¶
func WithHost(next echo.HandlerFunc) echo.HandlerFunc
WithHost middleware guarantees that all incoming HTTP requests include the correct "Host" value in their headers
Types ¶
This section is empty.
Source Files