[chore] The Big Middleware and API Refactor (tm) (#1250)

* interim commit: start refactoring middlewares into package under router

* another interim commit, this is becoming a big job

* another fucking massive interim commit

* refactor bookmarks to new style

* ambassador, wiz zeze commits you are spoiling uz

* she compiles, we're getting there

* we're just normal men; we're just innocent men

* apiutil

* whoopsie

* i'm glad noone reads commit msgs haha :blob_sweat:

* use that weirdo go-bytesize library for maxMultipartMemory

* fix media module paths

internal/api/util/errorhandling.go

@@ -0,0 +1,132 @@
+/*
+   GoToSocial
+   Copyright (C) 2021-2022 GoToSocial Authors admin@gotosocial.org
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Affero General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU Affero General Public License for more details.
+
+   You should have received a copy of the GNU Affero General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package util
+
+import (
+	"context"
+	"net/http"
+
+	"codeberg.org/gruf/go-kv"
+	"github.com/gin-gonic/gin"
+	apimodel "github.com/superseriousbusiness/gotosocial/internal/api/model"
+	"github.com/superseriousbusiness/gotosocial/internal/config"
+	"github.com/superseriousbusiness/gotosocial/internal/gtserror"
+	"github.com/superseriousbusiness/gotosocial/internal/log"
+)
+
+// TODO: add more templated html pages here for different error types
+
+// NotFoundHandler serves a 404 html page through the provided gin context,
+// if accept is 'text/html', or just returns a json error if 'accept' is empty
+// or application/json.
+//
+// When serving html, NotFoundHandler calls the provided InstanceGet function
+// to fetch the apimodel representation of the instance, for serving in the
+// 404 header and footer.
+//
+// If an error is returned by InstanceGet, the function will panic.
+func NotFoundHandler(c *gin.Context, instanceGet func(ctx context.Context, domain string) (*apimodel.Instance, gtserror.WithCode), accept string) {
+	switch accept {
+	case string(TextHTML):
+		host := config.GetHost()
+		instance, err := instanceGet(c.Request.Context(), host)
+		if err != nil {
+			panic(err)
+		}
+
+		c.HTML(http.StatusNotFound, "404.tmpl", gin.H{
+			"instance": instance,
+		})
+	default:
+		c.JSON(http.StatusNotFound, gin.H{"error": http.StatusText(http.StatusNotFound)})
+	}
+}
+
+// genericErrorHandler is a more general version of the NotFoundHandler, which can
+// be used for serving either generic error pages with some rendered help text,
+// or just some error json if the caller prefers (or has no preference).
+func genericErrorHandler(c *gin.Context, instanceGet func(ctx context.Context, domain string) (*apimodel.Instance, gtserror.WithCode), accept string, errWithCode gtserror.WithCode) {
+	switch accept {
+	case string(TextHTML):
+		host := config.GetHost()
+		instance, err := instanceGet(c.Request.Context(), host)
+		if err != nil {
+			panic(err)
+		}
+
+		c.HTML(errWithCode.Code(), "error.tmpl", gin.H{
+			"instance": instance,
+			"code":     errWithCode.Code(),
+			"error":    errWithCode.Safe(),
+		})
+	default:
+		c.JSON(errWithCode.Code(), gin.H{"error": errWithCode.Safe()})
+	}
+}
+
+// ErrorHandler takes the provided gin context and errWithCode and tries to serve
+// a helpful error to the caller. It will do content negotiation to figure out if
+// the caller prefers to see an html page with the error rendered there. If not, or
+// if something goes wrong during the function, it will recover and just try to serve
+// an appropriate application/json content-type error.
+func ErrorHandler(c *gin.Context, errWithCode gtserror.WithCode, instanceGet func(ctx context.Context, domain string) (*apimodel.Instance, gtserror.WithCode)) {
+	// set the error on the gin context so that it can be logged
+	// in the gin logger middleware (internal/router/logger.go)
+	c.Error(errWithCode) //nolint:errcheck
+
+	// discover if we're allowed to serve a nice html error page,
+	// or if we should just use a json. Normally we would want to
+	// check for a returned error, but if an error occurs here we
+	// can just fall back to default behavior (serve json error).
+	accept, _ := NegotiateAccept(c, HTMLOrJSONAcceptHeaders...)
+
+	if errWithCode.Code() == http.StatusNotFound {
+		// use our special not found handler with useful status text
+		NotFoundHandler(c, instanceGet, accept)
+	} else {
+		genericErrorHandler(c, instanceGet, accept, errWithCode)
+	}
+}
+
+// OAuthErrorHandler is a lot like ErrorHandler, but it specifically returns errors
+// that are compatible with https://datatracker.ietf.org/doc/html/rfc6749#section-5.2,
+// but serializing errWithCode.Error() in the 'error' field, and putting any help text
+// from the error in the 'error_description' field. This means you should be careful not
+// to pass any detailed errors (that might contain sensitive information) into the
+// errWithCode.Error() field, since the client will see this. Use your noggin!
+func OAuthErrorHandler(c *gin.Context, errWithCode gtserror.WithCode) {
+	l := log.WithFields(kv.Fields{
+		{"path", c.Request.URL.Path},
+		{"error", errWithCode.Error()},
+		{"help", errWithCode.Safe()},
+	}...)
+
+	statusCode := errWithCode.Code()
+
+	if statusCode == http.StatusInternalServerError {
+		l.Error("Internal Server Error")
+	} else {
+		l.Debug("handling OAuth error")
+	}
+
+	c.JSON(statusCode, gin.H{
+		"error":             errWithCode.Error(),
+		"error_description": errWithCode.Safe(),
+	})
+}

internal/api/util/mime.go

@@ -0,0 +1,36 @@
+/*
+   GoToSocial
+   Copyright (C) 2021-2022 GoToSocial Authors admin@gotosocial.org
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Affero General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU Affero General Public License for more details.
+
+   You should have received a copy of the GNU Affero General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package util
+
+// MIME represents a mime-type.
+type MIME string
+
+// MIME type
+const (
+	AppJSON           MIME = `application/json`
+	AppXML            MIME = `application/xml`
+	AppRSSXML         MIME = `application/rss+xml`
+	AppActivityJSON   MIME = `application/activity+json`
+	AppActivityLDJSON MIME = `application/ld+json; profile="https://www.w3.org/ns/activitystreams"`
+	AppForm           MIME = `application/x-www-form-urlencoded`
+	MultipartForm     MIME = `multipart/form-data`
+	TextXML           MIME = `text/xml`
+	TextHTML          MIME = `text/html`
+	TextCSS           MIME = `text/css`
+)

internal/api/util/negotiate.go

@@ -0,0 +1,104 @@
+/*
+   GoToSocial
+   Copyright (C) 2021-2022 GoToSocial Authors admin@gotosocial.org
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Affero General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU Affero General Public License for more details.
+
+   You should have received a copy of the GNU Affero General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package util
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ActivityPubAcceptHeaders represents the Accept headers mentioned here:
+var ActivityPubAcceptHeaders = []MIME{
+	AppActivityJSON,
+	AppActivityLDJSON,
+}
+
+// JSONAcceptHeaders is a slice of offers that just contains application/json types.
+var JSONAcceptHeaders = []MIME{
+	AppJSON,
+}
+
+// HTMLOrJSONAcceptHeaders is a slice of offers that prefers TextHTML and will
+// fall back to JSON if necessary. This is useful for error handling, since it can
+// be used to serve a nice HTML page if the caller accepts that, or just JSON if not.
+var HTMLOrJSONAcceptHeaders = []MIME{
+	TextHTML,
+	AppJSON,
+}
+
+// HTMLAcceptHeaders is a slice of offers that just contains text/html types.
+var HTMLAcceptHeaders = []MIME{
+	TextHTML,
+}
+
+// HTMLOrActivityPubHeaders matches text/html first, then activitypub types.
+// This is useful for user URLs that a user might go to in their browser.
+// https://www.w3.org/TR/activitypub/#retrieving-objects
+var HTMLOrActivityPubHeaders = []MIME{
+	TextHTML,
+	AppActivityJSON,
+	AppActivityLDJSON,
+}
+
+// NegotiateAccept takes the *gin.Context from an incoming request, and a
+// slice of Offers, and performs content negotiation for the given request
+// with the given content-type offers. It will return a string representation
+// of the first suitable content-type, or an error if something goes wrong or
+// a suitable content-type cannot be matched.
+//
+// For example, if the request in the *gin.Context has Accept headers of value
+// [application/json, text/html], and the provided offers are of value
+// [application/json, application/xml], then the returned string will be
+// 'application/json', which indicates the content-type that should be returned.
+//
+// If the length of offers is 0, then an error will be returned, so this function
+// should only be called in places where format negotiation is actually needed.
+//
+// If there are no Accept headers in the request, then the first offer will be returned,
+// under the assumption that it's better to serve *something* than error out completely.
+//
+// Callers can use the offer slices exported in this package as shortcuts for
+// often-used Accept types.
+//
+// See https://developer.mozilla.org/en-US/docs/Web/HTTP/Content_negotiation#server-driven_content_negotiation
+func NegotiateAccept(c *gin.Context, offers ...MIME) (string, error) {
+	if len(offers) == 0 {
+		return "", errors.New("no format offered")
+	}
+
+	strings := []string{}
+	for _, o := range offers {
+		strings = append(strings, string(o))
+	}
+
+	accepts := c.Request.Header.Values("Accept")
+	if len(accepts) == 0 {
+		// there's no accept header set, just return the first offer
+		return strings[0], nil
+	}
+
+	format := c.NegotiateFormat(strings...)
+	if format == "" {
+		return "", fmt.Errorf("no format can be offered for requested Accept header(s) %s; this endpoint offers %s", accepts, offers)
+	}
+
+	return format, nil
+}

internal/api/util/signaturectx.go

@@ -0,0 +1,41 @@
+/*
+   GoToSocial
+   Copyright (C) 2021-2022 GoToSocial Authors admin@gotosocial.org
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU Affero General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU Affero General Public License for more details.
+
+   You should have received a copy of the GNU Affero General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+package util
+
+import (
+	"context"
+
+	"github.com/gin-gonic/gin"
+	"github.com/superseriousbusiness/gotosocial/internal/ap"
+)
+
+// TransferSignatureContext transfers a signature verifier and signature from a gin context to a go context.
+func TransferSignatureContext(c *gin.Context) context.Context {
+	ctx := c.Request.Context()
+
+	if verifier, signed := c.Get(string(ap.ContextRequestingPublicKeyVerifier)); signed {
+		ctx = context.WithValue(ctx, ap.ContextRequestingPublicKeyVerifier, verifier)
+	}
+
+	if signature, signed := c.Get(string(ap.ContextRequestingPublicKeySignature)); signed {
+		ctx = context.WithValue(ctx, ap.ContextRequestingPublicKeySignature, signature)
+	}
+
+	return ctx
+}