simplexcalc/internal/api/api.go

// Package api is the bot's HTTP API, through which another program
// reads the bot's chats.
//
// Every request must carry the credential, as "Authorization: Bearer
// {credential}"; with no credential configured, every request is
// refused. No path is exempt.
//
// Handlers call the chat client on the request's own goroutine. Doing
// so from the chat client's event handler would wait forever, since
// that goroutine also delivers the responses (see simplex.EventHandler).
package api

import (
	"context"
	"crypto/subtle"
	"encoding/json"
	"log/slog"
	"net/http"
	"strconv"
	"strings"
	"time"

	"github.com/go-chi/chi/v5"
	"github.com/go-chi/chi/v5/middleware"
	"sneak.berlin/go/simplexcalc/internal/simplex"
)

const (
	// maxBodyBytes caps a request body.
	maxBodyBytes = 64 << 10

	// requestTimeout bounds the work behind one request, which is
	// mostly waiting for the chat client.
	requestTimeout = 10 * time.Second

	// Limits on clients that send or read slowly. writeTimeout outlasts
	// requestTimeout, so a handler that ran out of time can still
	// answer.
	readHeaderTimeout = 5 * time.Second
	readTimeout       = 10 * time.Second
	writeTimeout      = requestTimeout + 5*time.Second
	idleTimeout       = 60 * time.Second
)

// ChatClient is the part of the chat client the API uses.
// *simplex.Client provides it.
type ChatClient interface {
	// Contacts returns the contacts of the user userID.
	Contacts(ctx context.Context, userID int64) ([]simplex.Contact, error)
}

// Params configures New.
type Params struct {
	Log *slog.Logger

	// Client is the chat client, and UserID the bot's user profile in
	// it.
	Client ChatClient
	UserID int64

	// Port is the TCP port to listen on, on all interfaces.
	Port int

	// Token is the credential every request must carry. Empty refuses
	// every request.
	Token string
}

// New returns the API's server. The caller starts it with
// ListenAndServe and stops it with Shutdown.
func New(p Params) *http.Server {
	if p.Token == "" {
		p.Log.Warn("API_TOKEN_FILE is not set, so the API refuses every request")
	}

	h := &handlers{log: p.Log, client: p.Client, userID: p.UserID, token: p.Token}

	router := chi.NewRouter()
	router.Use(securityHeaders, h.authenticate,
		middleware.RequestSize(maxBodyBytes), withTimeout)
	router.NotFound(func(w http.ResponseWriter, _ *http.Request) {
		h.respondError(w, http.StatusNotFound, "not found")
	})
	router.MethodNotAllowed(func(w http.ResponseWriter, _ *http.Request) {
		h.respondError(w, http.StatusMethodNotAllowed, "method not allowed")
	})
	router.Route("/api/v1", func(r chi.Router) {
		r.Get("/chats", h.handleChats())
	})

	return &http.Server{
		Addr:              ":" + strconv.Itoa(p.Port),
		Handler:           router,
		ReadHeaderTimeout: readHeaderTimeout,
		ReadTimeout:       readTimeout,
		WriteTimeout:      writeTimeout,
		IdleTimeout:       idleTimeout,
		// net/http's own messages, such as a handler's panic, go to the
		// same JSON log as everything else.
		ErrorLog: slog.NewLogLogger(p.Log.Handler(), slog.LevelError),
	}
}

// handlers holds what the handlers share.
type handlers struct {
	log    *slog.Logger
	client ChatClient
	userID int64
	token  string
}

// authenticate lets a request through only if it carries the
// credential. With no credential it refuses everything, and must:
// ConstantTimeCompare finds two empty strings equal, so an empty bearer
// would get in.
func (h *handlers) authenticate(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		scheme, credential, _ := strings.Cut(r.Header.Get("Authorization"), " ")

		if h.token == "" || !strings.EqualFold(scheme, "Bearer") ||
			subtle.ConstantTimeCompare([]byte(credential), []byte(h.token)) != 1 {
			w.Header().Set("WWW-Authenticate", "Bearer")
			h.respondError(w, http.StatusUnauthorized, "unauthorized")

			return
		}

		next.ServeHTTP(w, r)
	})
}

// respond sends v as the JSON body of a response with status.
func (h *handlers) respond(w http.ResponseWriter, status int, v any) {
	w.Header().Set("Content-Type", "application/json")
	w.WriteHeader(status)

	err := json.NewEncoder(w).Encode(v)
	if err != nil {
		h.log.Warn("sending a response", "error", err)
	}
}

// respondError sends status with a chosen sentence. An error's own text
// never goes to the client, since it can describe the machine; it goes
// to the log.
func (h *handlers) respondError(w http.ResponseWriter, status int, sentence string) {
	h.respond(w, status, struct {
		Error string `json:"error"`
	}{sentence})
}

// securityHeaders go on every response. The API returns JSON to
// programs, so a browser may not frame, sniff, cache or refer from it,
// and must reach it over HTTPS.
func securityHeaders(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		header := w.Header()
		header.Set("X-Content-Type-Options", "nosniff")
		header.Set("Content-Security-Policy",
			"default-src 'none'; frame-ancestors 'none'")
		header.Set("X-Frame-Options", "DENY")
		header.Set("Referrer-Policy", "no-referrer")
		header.Set("Strict-Transport-Security",
			"max-age=31536000; includeSubDomains")
		header.Set("Cache-Control", "no-store")

		next.ServeHTTP(w, r)
	})
}

// withTimeout ends each request's context after requestTimeout, so a
// handler waiting on the chat client gives up and answers.
func withTimeout(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		ctx, cancel := context.WithTimeout(r.Context(), requestTimeout)
		defer cancel()

		next.ServeHTTP(w, r.WithContext(ctx))
	})
}