diff --git a/mail/internal/mailapi/contract_test.go b/mail/internal/mailapi/contract_test.go new file mode 100644 index 00000000..a43afb07 --- /dev/null +++ b/mail/internal/mailapi/contract_test.go @@ -0,0 +1,441 @@ +// QA-06: Schnittstellen-Vertragstests fuer die Mail-API v1. +// +// Im Unterschied zu TestOpenAPIDocument_MatchesActualEndpoints +// (openapi_test.go, INT-01) prueft dieses Dateipendant nicht nur, dass +// eine Route im OpenAPI-Dokument aufgeloest werden kann, sondern dass +// tatsaechliche Antworten (Statuscode + Rumpf) je Szenario gegen das +// fuer diese Route dokumentierte Schema validieren — mit +// openapi3filter, nicht mit einem selbstgebauten Vergleich. +package mailapi + +import ( + "context" + "errors" + "io" + "net/http" + "net/http/httptest" + "strings" + "testing" + + "github.com/getkin/kin-openapi/openapi3" + "github.com/getkin/kin-openapi/openapi3filter" + "github.com/getkin/kin-openapi/routers" + "github.com/getkin/kin-openapi/routers/gorillamux" + + "gitea.perlbach24.de/scripte/nexarch/mail/internal/moduleauth" + "gitea.perlbach24.de/scripte/nexarch/mail/internal/search" + "gitea.perlbach24.de/scripte/nexarch/mail/internal/storage" +) + +// contractSearchFake braucht zusaetzlich zu fakeSearchClient +// (mailapi_test.go) einen Fehlerpfad, um die dokumentierten +// 502-Antworten ueberhaupt ausloesen zu koennen, deshalb ein eigenes, +// in dieser Datei isoliertes Fake statt einer Aenderung an INT-01s +// bestehenden Test-Fakes. +type contractSearchFake struct { + docs map[string]map[string]search.Document + searchErr error + getByIDErr error +} + +func newContractSearchFake() *contractSearchFake { + return &contractSearchFake{docs: map[string]map[string]search.Document{}} +} + +func (f *contractSearchFake) put(tenant string, doc search.Document) { + if f.docs[tenant] == nil { + f.docs[tenant] = map[string]search.Document{} + } + f.docs[tenant][doc.MessageID] = doc +} + +func (f *contractSearchFake) Search(_ context.Context, tenantSlug, _ string) ([]search.Result, error) { + if f.searchErr != nil { + return nil, f.searchErr + } + var out []search.Result + for _, doc := range f.docs[tenantSlug] { + out = append(out, search.Result{MessageID: doc.MessageID, Subject: doc.Subject, SentAtUnixEpoch: doc.SentAtUnixEpoch}) + } + return out, nil +} + +func (f *contractSearchFake) GetByMessageID(_ context.Context, tenantSlug, messageID string) (search.Document, bool, error) { + if f.getByIDErr != nil { + return search.Document{}, false, f.getByIDErr + } + doc, ok := f.docs[tenantSlug][messageID] + return doc, ok, nil +} + +type contractStorageFake struct { + services map[string]*storage.Service +} + +func newContractStorageFake(t *testing.T, tenants ...string) *contractStorageFake { + t.Helper() + f := &contractStorageFake{services: map[string]*storage.Service{}} + for _, tenant := range tenants { + f.services[tenant] = storage.NewService(storage.NewLocalDriver(t.TempDir()), contractNoopUsageReporter{}, tenant) + } + return f +} + +func (f *contractStorageFake) ServiceFor(tenantSlug string) (*storage.Service, error) { + svc, ok := f.services[tenantSlug] + if !ok { + return nil, errors.New("mailapi: unbekannter mandant") + } + return svc, nil +} + +type contractNoopUsageReporter struct{} + +func (contractNoopUsageReporter) Report(context.Context, string, string, int64) error { return nil } + +// contractServer buendelt den echten httptest-Server (echte Handler +// aus mailapi.go) mit dem fuer die Vertragsprüfung geladenen +// OpenAPI-Dokument und -Router. +type contractServer struct { + url string + issuer *moduleauth.TestIssuer + doc *openapi3.T + router routers.Router +} + +func (cs *contractServer) token(subject, tenant string) string { + return cs.issuer.Token(subject, tenant, "user", "mail", "") +} + +// buildContractServer baut den echten httptest-Server fuer gegebene +// Fakes auf, inklusive eigenem Testschluesselpaar (jeder Aufruf ist +// unabhaengig — ein Token aus einem Aufruf passt NICHT zum Verifier +// eines anderen Aufrufs). +func buildContractServer(t *testing.T, sc *contractSearchFake, sp *contractStorageFake) *contractServer { + t.Helper() + srv := NewServer(sc, sp) + mux := http.NewServeMux() + verifier, issuer := moduleauth.NewTestVerifierAndIssuer() + srv.RegisterRoutes(mux, verifier) + httpSrv := httptest.NewServer(mux) + t.Cleanup(httpSrv.Close) + + doc := loadContractDoc(t) + router, err := gorillamux.NewRouter(doc) + if err != nil { + t.Fatalf("router aus openapi.yaml bauen: %v", err) + } + return &contractServer{url: httpSrv.URL, issuer: issuer, doc: doc, router: router} +} + +func setupContractServer(t *testing.T) (*contractServer, *contractSearchFake) { + t.Helper() + sc := newContractSearchFake() + sp := newContractStorageFake(t, "mandant-a", "mandant-b") + return buildContractServer(t, sc, sp), sc +} + +// putContractAttachment legt einen Anhang direkt im Storage-Fake des +// angegebenen Mandanten ab, fuer den Download-Erfolgsfall. +func putContractAttachment(t *testing.T, sp *contractStorageFake, tenant, messageID string, index int, content string) { + t.Helper() + svc, err := sp.ServiceFor(tenant) + if err != nil { + t.Fatalf("ServiceFor %s: %v", tenant, err) + } + if _, err := svc.Put(context.Background(), storage.ObjectKey(messageID, index), strings.NewReader(content), int64(len(content)), "text/plain"); err != nil { + t.Fatalf("anhang ablegen: %v", err) + } +} + +func loadContractDoc(t *testing.T) *openapi3.T { + t.Helper() + loader := openapi3.NewLoader() + doc, err := loader.LoadFromFile("openapi.yaml") + if err != nil { + t.Fatalf("openapi.yaml laden: %v", err) + } + if err := doc.Validate(context.Background()); err != nil { + t.Fatalf("openapi.yaml validieren: %v", err) + } + return doc +} + +func doContractRequest(t *testing.T, cs *contractServer, method, path, bearer string) (*http.Request, *http.Response, []byte) { + t.Helper() + req, err := http.NewRequest(method, cs.url+path, nil) + if err != nil { + t.Fatalf("request bauen: %v", err) + } + if bearer != "" { + req.Header.Set("Authorization", "Bearer "+bearer) + } + resp, err := http.DefaultClient.Do(req) + if err != nil { + t.Fatalf("request ausfuehren: %v", err) + } + defer func() { _ = resp.Body.Close() }() + body, err := io.ReadAll(resp.Body) + if err != nil { + t.Fatalf("antwortkoerper lesen: %v", err) + } + return req, resp, body +} + +// validateResponseAgainstSpec ist die Kernpruefung von +// Akzeptanzkriterium 2: die tatsaechliche Antwort (Statuscode + Rumpf) +// wird gegen das fuer DIESE Route in openapi.yaml dokumentierte Schema +// geprueft. IncludeResponseStatus=true laesst den Test zusaetzlich +// fehlschlagen, falls ein Statuscode zurueckkommt, der fuer diese +// Route ueberhaupt nicht dokumentiert ist. +func validateResponseAgainstSpec(t *testing.T, cs *contractServer, req *http.Request, resp *http.Response, body []byte) { + t.Helper() + route, pathParams, err := cs.router.FindRoute(req) + if err != nil { + t.Fatalf("route fuer %s %s nicht im OpenAPI-Dokument gefunden: %v", req.Method, req.URL.Path, err) + } + respInput := &openapi3filter.ResponseValidationInput{ + RequestValidationInput: &openapi3filter.RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + }, + Status: resp.StatusCode, + Header: resp.Header, + Options: &openapi3filter.Options{IncludeResponseStatus: true}, + } + respInput.SetBodyBytes(body) + if err := openapi3filter.ValidateResponse(context.Background(), respInput); err != nil { + t.Fatalf("antwort weicht von openapi.yaml ab (%s %s -> %d): %v", req.Method, req.URL.Path, resp.StatusCode, err) + } +} + +// validateRequestAgainstSpec prueft zusaetzlich, dass eine +// strukturell wohlgeformte Anfrage selbst den Parameter-Schemata aus +// openapi.yaml entspricht. NoopAuthenticationFunc wird gesetzt, weil +// die Durchsetzung des Modul-Tokens bereits durch +// TestRoutes_RejectMissingOrInvalidToken (mailapi_test.go) abgedeckt +// ist — hier geht es ausschliesslich um die Form der Anfrage. +func validateRequestAgainstSpec(t *testing.T, cs *contractServer, req *http.Request) { + t.Helper() + route, pathParams, err := cs.router.FindRoute(req) + if err != nil { + t.Fatalf("route fuer %s %s nicht im OpenAPI-Dokument gefunden: %v", req.Method, req.URL.Path, err) + } + reqInput := &openapi3filter.RequestValidationInput{ + Request: req, + PathParams: pathParams, + Route: route, + Options: &openapi3filter.Options{AuthenticationFunc: openapi3filter.NoopAuthenticationFunc}, + } + if err := openapi3filter.ValidateRequest(context.Background(), reqInput); err != nil { + t.Fatalf("anfrage entspricht nicht dem in openapi.yaml dokumentierten schema (%s %s): %v", req.Method, req.URL.Path, err) + } +} + +// TestContract_DocumentedEndpointsMatchActualBehavior ist der +// eigentliche Vertragstest (Akzeptanzkriterium 1+2): fuer jeden in +// openapi.yaml dokumentierten Endpunkt mindestens ein Szenario, das +// die tatsaechliche Antwort des echten Servers gegen das dokumentierte +// Schema prueft. Am Ende der Funktion wird zusaetzlich programmatisch +// sichergestellt, dass KEIN in openapi.yaml dokumentierter +// Pfad+Methode-Kombination ohne Testfall bleibt (Akzeptanzkriterium 1 +// bleibt damit auch bei kuenftigen Erweiterungen von openapi.yaml +// erzwungen, statt nur einmalig behauptet). +func TestContract_DocumentedEndpointsMatchActualBehavior(t *testing.T) { + doc := loadContractDoc(t) + + type testCase struct { + name string + specMethod string + specPath string // Pfad wie in openapi.yaml "paths:", ohne Server-Praefix + wantStatus int + checkValid bool // Anfrage ist strukturell wohlgeformt -> zusaetzlich gegen Parameter-Schema pruefen + setup func(t *testing.T) (cs *contractServer, method, path, bearer string) + } + + cases := []testCase{ + { + name: "liste_mit_treffern", + specMethod: http.MethodGet, specPath: "/messages", + wantStatus: http.StatusOK, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, sc := setupContractServer(t) + sc.put("mandant-a", search.Document{MessageID: "a-1", Subject: "Betreff", SentAtUnixEpoch: 100}) + return cs, http.MethodGet, "/api/v1/mail/messages", cs.token("u1", "mandant-a") + }, + }, + { + name: "liste_ohne_token", + specMethod: http.MethodGet, specPath: "/messages", + wantStatus: http.StatusUnauthorized, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, _ := setupContractServer(t) + return cs, http.MethodGet, "/api/v1/mail/messages", "" + }, + }, + { + name: "liste_vorgelagerter_dienst_fehlt", + specMethod: http.MethodGet, specPath: "/messages", + wantStatus: http.StatusBadGateway, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, sc := setupContractServer(t) + sc.searchErr = errors.New("manticore nicht erreichbar") + return cs, http.MethodGet, "/api/v1/mail/messages", cs.token("u1", "mandant-a") + }, + }, + { + name: "detail_eigener_mandant", + specMethod: http.MethodGet, specPath: "/messages/{messageID}", + wantStatus: http.StatusOK, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, sc := setupContractServer(t) + sc.put("mandant-a", search.Document{ + MessageID: "a-1", Subject: "Betreff", Body: "Inhalt", + Sender: "absender@example.com", Mailbox: "INBOX", SentAtUnixEpoch: 42, + }) + return cs, http.MethodGet, "/api/v1/mail/messages/a-1", cs.token("u1", "mandant-a") + }, + }, + { + name: "detail_nicht_gefunden", + specMethod: http.MethodGet, specPath: "/messages/{messageID}", + wantStatus: http.StatusNotFound, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, _ := setupContractServer(t) + return cs, http.MethodGet, "/api/v1/mail/messages/unbekannt", cs.token("u1", "mandant-a") + }, + }, + { + name: "detail_vorgelagerter_dienst_fehlt", + specMethod: http.MethodGet, specPath: "/messages/{messageID}", + wantStatus: http.StatusBadGateway, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, sc := setupContractServer(t) + sc.getByIDErr = errors.New("manticore nicht erreichbar") + return cs, http.MethodGet, "/api/v1/mail/messages/a-1", cs.token("u1", "mandant-a") + }, + }, + { + name: "anhang_download_erfolg", + specMethod: http.MethodGet, specPath: "/messages/{messageID}/attachments/{index}", + wantStatus: http.StatusOK, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + sc := newContractSearchFake() + sc.put("mandant-a", search.Document{MessageID: "a-1", Subject: "Mit Anhang"}) + sp := newContractStorageFake(t, "mandant-a") + putContractAttachment(t, sp, "mandant-a", "a-1", 0, "anhangsinhalt") + cs := buildContractServer(t, sc, sp) + return cs, http.MethodGet, "/api/v1/mail/messages/a-1/attachments/0", cs.token("u1", "mandant-a") + }, + }, + { + name: "anhang_ungueltiger_index", + specMethod: http.MethodGet, specPath: "/messages/{messageID}/attachments/{index}", + wantStatus: http.StatusBadRequest, checkValid: false, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, _ := setupContractServer(t) + return cs, http.MethodGet, "/api/v1/mail/messages/a-1/attachments/abc", cs.token("u1", "mandant-a") + }, + }, + { + name: "anhang_nicht_gefunden", + specMethod: http.MethodGet, specPath: "/messages/{messageID}/attachments/{index}", + wantStatus: http.StatusNotFound, checkValid: true, + setup: func(t *testing.T) (*contractServer, string, string, string) { + cs, sc := setupContractServer(t) + sc.put("mandant-a", search.Document{MessageID: "a-1", Subject: "Ohne hochgeladenen anhang"}) + return cs, http.MethodGet, "/api/v1/mail/messages/a-1/attachments/9", cs.token("u1", "mandant-a") + }, + }, + } + + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + cs, method, path, bearer := tc.setup(t) + req, resp, body := doContractRequest(t, cs, method, path, bearer) + if resp.StatusCode != tc.wantStatus { + t.Fatalf("erwartete status %d, habe %d (body: %s)", tc.wantStatus, resp.StatusCode, body) + } + if tc.checkValid { + validateRequestAgainstSpec(t, cs, req) + } + validateResponseAgainstSpec(t, cs, req, resp, body) + }) + } + + documented := map[string]bool{} + for path, item := range doc.Paths.Map() { + for method := range item.Operations() { + documented[strings.ToUpper(method)+" "+path] = false + } + } + for _, tc := range cases { + key := strings.ToUpper(tc.specMethod) + " " + tc.specPath + if _, ok := documented[key]; !ok { + t.Fatalf("testfall %q bezieht sich auf einen in openapi.yaml nicht dokumentierten endpunkt: %s", tc.name, key) + } + documented[key] = true + } + for key, covered := range documented { + if !covered { + t.Errorf("endpunkt %q ist in openapi.yaml dokumentiert, aber durch keinen testfall in dieser tabelle abgedeckt", key) + } + } +} + +// TestContract_DetectsBreakingChange ist die geforderte +// Pflichtpruefung ("Test: absichtlich eingefuegte Abweichung wird vom +// Vertragstest erkannt"): ein Handler, der GENAU den dokumentierten +// Pfad bedient, aber ein in openapi.yaml als required deklariertes +// Feld ("sentAt" in MessageListItem) weglaesst, muss vom +// Vertragstest-Mechanismus als Abweichung erkannt werden — gegen das +// echte, unveraenderte openapi.yaml. +func TestContract_DetectsBreakingChange(t *testing.T) { + doc := loadContractDoc(t) + router, err := gorillamux.NewRouter(doc) + if err != nil { + t.Fatalf("router aus openapi.yaml bauen: %v", err) + } + + broken := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) { + w.Header().Set("Content-Type", "application/json") + w.WriteHeader(http.StatusOK) + _, _ = w.Write([]byte(`{"messages":[{"messageId":"a-1","subject":"Betreff"}]}`)) + })) + t.Cleanup(broken.Close) + + req, err := http.NewRequest(http.MethodGet, broken.URL+"/api/v1/mail/messages", nil) + if err != nil { + t.Fatalf("request bauen: %v", err) + } + resp, err := http.DefaultClient.Do(req) + if err != nil { + t.Fatalf("request ausfuehren: %v", err) + } + defer func() { _ = resp.Body.Close() }() + body, err := io.ReadAll(resp.Body) + if err != nil { + t.Fatalf("antwortkoerper lesen: %v", err) + } + + route, pathParams, err := router.FindRoute(req) + if err != nil { + t.Fatalf("route nicht gefunden: %v", err) + } + respInput := &openapi3filter.ResponseValidationInput{ + RequestValidationInput: &openapi3filter.RequestValidationInput{Request: req, PathParams: pathParams, Route: route}, + Status: resp.StatusCode, + Header: resp.Header, + } + respInput.SetBodyBytes(body) + + err = openapi3filter.ValidateResponse(context.Background(), respInput) + if err == nil { + t.Fatal("erwartete einen fehler: antwort fehlt pflichtfeld \"sentAt\" gegenueber openapi.yaml, der vertragstest haette das erkennen muessen") + } + if !strings.Contains(err.Error(), "sentAt") { + t.Fatalf("fehler erkannt, nennt aber nicht das erwartete fehlende feld \"sentAt\": %v", err) + } + t.Logf("vertragstest hat die eingefuegte abweichung korrekt erkannt: %v", err) +}