Added the opportunities REST API, read-only apart from their marks, described in OpenAPI 3.1 with swag

GET /api/opportunities lists the stored opportunities, newest release first,
a page at a time (offset, and limit up to 100, default 50); has_more says
whether another page follows. GET /api/opportunities/{uuid} returns one with
its releases. PUT and DELETE /api/opportunities/{uuid}/marks/{mark} set and
clear one mark (hidden, skipped, interested, bid_submitted, won, lost) and
return them all; won and lost exclude each other (409). The API uses the
types in internal/types, and changing a mark is made atomic, as the store
replaces all of an opportunity's marks at once. The marks are found by
reflection: every bool field of types.OpportunityMarks, by its JSON name, so
a new mark needs no API change.

The API has one entry point, api.New, with its dependencies as options
(api.WithStore), and the server only mounts it under /api, keeping the
middleware. New resources are added inside internal/api. job-search serve
passes server.WithStore when database.file is set, opening the store before
the server; without one there are no opportunity routes.

The API is described by swag v2 annotations on the handlers. go generate
writes the OpenAPI 3.1 description (git-ignored, like the OCDS types), which
the server embeds and serves at /api/openapi.json, with Swagger UI at
/api/docs. A test checks the description and the routes match. swag is in
the README's dev tools, pinned to v2.0.0-rc6, and the build now needs it.

internal/server/routes.go

@@ -60,6 +60,7 @@ func (s *Server) routes() (http.Handler, error) {
 		if s.csrf.TokenEnabled() {
 			apiRouter.Get("/csrf", s.csrf.IssueHandler)
 		}
+		s.api.Routes(apiRouter)
 	})
 
 	// WebSocket (no compression middleware: permessage-deflate is separate)

internal/server/server.go

@@ -17,9 +17,11 @@ import (
 
 	"github.com/pires/go-proxyproto"
 
+	"git.avsdev.uk/Go/job-search/internal/api"
 	"git.avsdev.uk/Go/job-search/internal/config"
 	"git.avsdev.uk/Go/job-search/internal/logging"
 	"git.avsdev.uk/Go/job-search/internal/middleware"
+	"git.avsdev.uk/Go/job-search/internal/store"
 	"git.avsdev.uk/Go/job-search/internal/util"
 	"git.avsdev.uk/Go/job-search/internal/websocket"
 )
@@ -61,6 +63,15 @@ func WithAccessLog(logger *log.Logger) Option {
 	}
 }
 
+// WithStore makes the server's API serve the opportunities in `store` under
+// /api/opportunities (see api.WithStore). Without it there are no
+// opportunity routes.
+func WithStore(store *store.Store) Option {
+	return func(s *Server) {
+		s.store = store
+	}
+}
+
 // WithMiddleware appends middleware to a group. This is the generic hook
 // (auth, metrics, tracing, custom header rules, ...).
 func WithMiddleware(group Group, middlewares ...Middleware) Option {
@@ -107,8 +118,12 @@ type Server struct {
 	proxyProtocolTrusted []netip.Prefix
 	csrf                 *middleware.CSRF
 	hub                  *websocket.Hub
-	started              time.Time
-	handler              http.Handler
+	// store is the opportunities' database, or nil for none.
+	store *store.Store
+	// api is the REST API mounted under /api, built from the options.
+	api     *api.API
+	started time.Time
+	handler http.Handler
 	// backgroundCtx is for background work, such as the rate limiters'
 	// janitors; backgroundCancel stops it.
 	backgroundCtx    context.Context
@@ -127,6 +142,7 @@ func New(conf *config.JSCServer, opts ...Option) (*Server, error) {
 	for _, option := range opts {
 		option(server)
 	}
+	server.api = api.New(api.WithStore(server.store))
 
 	var err error
 	server.trusted, err = util.ParseNetPrefixes(conf.Proxy.TrustedProxies)

internal/server/server_test.go

@@ -9,6 +9,7 @@ import (
 	"net/http"
 	"net/http/cookiejar"
 	"net/http/httptest"
+	"path/filepath"
 	"strings"
 	"sync"
 	"testing"
@@ -20,6 +21,8 @@ import (
 
 	"git.avsdev.uk/Go/job-search/internal/config"
 	"git.avsdev.uk/Go/job-search/internal/middleware"
+	"git.avsdev.uk/Go/job-search/internal/store"
+	"git.avsdev.uk/Go/job-search/internal/types"
 	ws "git.avsdev.uk/Go/job-search/internal/websocket"
 )
 
@@ -87,6 +90,31 @@ func clientWithJar(t *testing.T) *http.Client {
 	}
 }
 
+// apiClient returns a function making requests to the test server ts with
+// client c, sending body as JSON and, if withToken, the CSRF token tok.
+func apiClient(
+	t *testing.T, ts *httptest.Server, c *http.Client, tok csrfToken,
+) func(method, path, body string, withToken bool) *http.Response {
+	t.Helper()
+	return func(method, path, body string, withToken bool) *http.Response {
+		req, _ := http.NewRequest(method, ts.URL+path, strings.NewReader(body))
+		if body != "" {
+			req.Header.Set("Content-Type", "application/json")
+		}
+		if withToken {
+			req.Header.Set(tok.Header, tok.Token)
+		}
+		res, err := c.Do(req)
+		if err != nil {
+			t.Fatal(err)
+		}
+		t.Cleanup(func() {
+			res.Body.Close()
+		})
+		return res
+	}
+}
+
 // Unsafe API requests need the CSRF token: without it they are rejected
 // before routing; with it they reach the router (here, 405 from a GET-only
 // route).
@@ -307,3 +335,61 @@ func (b *syncBuffer) String() string {
 	defer b.mu.Unlock()
 	return b.buffer.String()
 }
+
+// With WithOpportunityStore the opportunities are served, and changing a mark
+// needs the CSRF token; without it there are no opportunity routes.
+func TestOpportunityRoutes(t *testing.T) {
+	opportunityStore, err := store.Open(
+		context.Background(),
+		filepath.Join(t.TempDir(), "server.db"),
+		store.WithAutoMigrate(),
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() {
+		opportunityStore.Close()
+	})
+	_, err = opportunityStore.SaveOpportunity(
+		context.Background(),
+		&types.Opportunity{
+			UUID:     "ocds-1",
+			UUIDType: "ocid",
+			Releases: []types.OpportunityRelease{
+				{
+					ReleaseID:   "r1",
+					ReleaseDate: time.Now(),
+					JSON:        "{}",
+				},
+			},
+		},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	ts := newTestServer(t, nil, WithStore(opportunityStore))
+	c := clientWithJar(t)
+	do := apiClient(t, ts, c, getToken(t, c, ts.URL))
+
+	if res := do("GET", "/api/opportunities", "", false); res.StatusCode != 200 {
+		t.Errorf("list: %d; want 200", res.StatusCode)
+	}
+	mark := "/api/opportunities/ocds-1/marks/interested"
+	if res := do("PUT", mark, "", false); res.StatusCode != http.StatusForbidden {
+		t.Errorf("mark without token: %d; want 403", res.StatusCode)
+	}
+	if res := do("PUT", mark, "", true); res.StatusCode != 200 {
+		t.Errorf("mark with token: %d; want 200", res.StatusCode)
+	}
+
+	without := newTestServer(t, nil)
+	res, err := http.Get(without.URL + "/api/opportunities")
+	if err != nil {
+		t.Fatal(err)
+	}
+	res.Body.Close()
+	if res.StatusCode != http.StatusNotFound {
+		t.Errorf("no store: %d; want 404", res.StatusCode)
+	}
+}