Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 10 additions & 4 deletions docs/COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,9 +115,15 @@ locale data can change between JDK releases.
- Intentional divergence: after a templated body file is edited, WireMock keeps
serving its cached compiled template until the mapping changes. BreakMock serves
the edited file immediately.
- Request journals differ for templated responses (WireMock logs the rendered body
in `responseDefinition`) and for gzip responses (WireMock logs the uncompressed
body). Served bytes are identical.
- Request journals follow WireMock for templated and gzip responses: the
`responseDefinition` is the definition after templating (rendered headers, and a
rendered body replacing `body`, `jsonBody` or `bodyFileName`), a template
execution error is journaled as its error response, and a gzip-encoded response
is journaled uncompressed without `Content-Encoding`. BreakMock keeps the
compressed bytes in memory and decodes them only when the journal is read.
- Java WireMock's capped journal occasionally retains one entry too few under
concurrent load. The concurrency suite records that reference defect as a
warning; BreakMock's own count must still be exact.
- Runtime comparisons cover two small workloads. See `BENCHMARKS.md` for the latest
optimized Go/Rust results and their limits; broader workloads remain unmeasured.

Expand Down Expand Up @@ -151,7 +157,7 @@ Consolidated local Go and Rust runs (2026-10-12), retained under
| Message waits, disabled journal | 5/5 | Existing origin substitution; new precedence cases use exact bytes |
| Concurrent journal | 16 invariants + 3 byte comparisons | Two exact admin responses; one with generated scalar substitutions |
| Templates inside 80 KB bodies, 3 requests each | 429/429 | Status and response bytes, including errors |
| Dynamic templates, edits and journal integrity | 238/238 | Exact bytes per request, at 2 sizes; random/time helpers by property |
| Dynamic templates, edits and journal integrity | 254/254 | Exact bytes per request, at 2 sizes; random/time helpers by property; 16 journal events by field and key order |

The last two rows were run on 2026-10-12 against Java with `template_differential.py --pad 80000 --repeat 3`
and `dynamic_template_differential.py`. That suite checks values that vary by request,
Expand Down
15 changes: 7 additions & 8 deletions docs/LARGE_JSON_OPTIMIZATION.md
Original file line number Diff line number Diff line change
Expand Up @@ -210,12 +210,10 @@ available there.
[COMPATIBILITY.md](COMPATIBILITY.md#byte-comparison-boundaries)).
- In the benchmark, every served response was compared byte-for-byte with Java's.
- Journal events were also compared with Java's (ids, timings and client details
removed). Static responses matched. Two differences remain, and both exist
unchanged in BreakMock before this work:
- For templated responses, Java journals the rendered body in
`responseDefinition`; BreakMock journals the template source.
- For gzip responses, Java journals the uncompressed body without
`Content-Encoding`; BreakMock journals the compressed bytes.
removed). When these benchmarks ran, static responses matched and two earlier
differences remained (templated `responseDefinition` and gzip bodies). Both
have since been fixed; the benchmark's `--journal-check strict` mode now passes
against Java for every workload.
- `scripts/template_differential.py --pad 80000 --repeat 3` reruns all 429
template cases inside 80 KB templates, 3 requests each: 429/429 identical to
Java. `scripts/dynamic_template_differential.py` (238 checks) confirms against
Expand Down Expand Up @@ -280,8 +278,9 @@ python3 scripts/json_benchmark.py --binary java=/tmp/wiremock.jar \
--output testdata/reports/benchmark-large-json.json
```

`--journal-check report` records the two known journal differences instead of
stopping the run. Between BreakMock builds, use the default `strict` mode.
`--journal-check report` records journal differences instead of stopping the run.
It was needed for the published runs, which predate the journal fixes; current
builds pass the default `strict` mode against Java.

Raw data: [end-to-end report](../testdata/reports/benchmark-large-json.json)
(including executable and JAR hashes, every round and the journal differences)
Expand Down
2 changes: 1 addition & 1 deletion pkg/breakmock/diagnostics_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,7 @@ func TestJavaDiagnosticGolden(t *testing.T) {
func TestTemplateErrorHasExactPlainBody(t *testing.T) {
s, _ := NewServer(Options{RootDir: t.TempDir()})
w := httptest.NewRecorder()
s.writeTemplateError(w, &TemplateExecutionError{Message: "1:0: sample"}, Mapping{"id": "example"})
s.writeTemplateError(w, &TemplateExecutionError{Message: "1:0: sample"}, Mapping{"id": "example"}, &Request{})
if w.Code != 500 || w.Body.String() != "[ERROR] 1:0: sample" || w.Header().Get("Content-Type") != "text/plain" || w.Header().Get("Matched-Stub-Id") != "example" {
t.Fatalf("%v %s", w.Result(), w.Body.String())
}
Expand Down
74 changes: 67 additions & 7 deletions pkg/breakmock/journal_storage_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ import (
"encoding/json"
"fmt"
"net/http/httptest"
"os"
"path/filepath"
"reflect"
"slices"
"strings"
"testing"
Expand Down Expand Up @@ -103,22 +106,79 @@ func TestJournalServesLoggedResponseBodies(t *testing.T) {
var journal struct {
Requests []struct {
Response struct {
Body string `json:"body"`
BodyAsBase64 string `json:"bodyAsBase64"`
Body string `json:"body"`
BodyAsBase64 string `json:"bodyAsBase64"`
Headers map[string]string `json:"headers"`
} `json:"response"`
} `json:"requests"`
}
if err = json.Unmarshal(admin.Body.Bytes(), &journal); err != nil || len(journal.Requests) != 2 {
t.Fatal(err, admin.Body.String())
}
// Newest first: the gzip response, then the plain response.
for i, served := range [][]byte{compressed.Body.Bytes(), plain.Body.Bytes()} {
logged := journal.Requests[i].Response
if logged.BodyAsBase64 != base64.StdEncoding.EncodeToString(served) || (i == 1 && logged.Body != body) {
t.Fatalf("logged response %d differs from served bytes", i)
// Newest first: the gzip response, then the plain response. As in WireMock,
// whose journal records the body before Jetty compresses it, both log the
// uncompressed body and the gzip response logs no Content-Encoding.
for i, logged := range []struct {
Body string `json:"body"`
BodyAsBase64 string `json:"bodyAsBase64"`
Headers map[string]string `json:"headers"`
}{journal.Requests[0].Response, journal.Requests[1].Response} {
if logged.BodyAsBase64 != base64.StdEncoding.EncodeToString([]byte(body)) || logged.Body != body {
t.Fatalf("logged response %d is not the uncompressed body", i)
}
if _, ok := logged.Headers["Content-Encoding"]; ok {
t.Fatalf("logged response %d keeps the server's Content-Encoding", i)
}
}
if !strings.Contains(admin.Body.String(), `"body" : "{\"name\":\"Zoë <b>\"`) {
t.Fatal("logged text body is not serialized with admin escaping")
}
}

func TestJournalLogsRenderedResponseDefinition(t *testing.T) {
root := t.TempDir()
os.MkdirAll(filepath.Join(root, "__files"), 0o755)
os.WriteFile(filepath.Join(root, "__files", "t.txt"), []byte("File {{request.query.a}}"), 0o644)
os.WriteFile(filepath.Join(root, "__files", "s.txt"), []byte("Static file"), 0o644)
s, err := NewServer(Options{RootDir: root})
if err != nil {
t.Fatal(err)
}
tpl := `"transformers":["response-template"]`
// Expected definitions captured from WireMock 4.0.0-beta.40.
for _, c := range []struct{ name, response, want string }{
{"inline body", `{"body":"Hi {{request.query.a}}",` + tpl + `}`, `{"status":200,"body":"Hi AA","transformers":["response-template"]}`},
{"headers", `{"body":"x","headers":{"X-A":"{{request.query.a}}","X-M":["{{request.query.a}}","two"]},` + tpl + `}`, `{"status":200,"body":"x","headers":{"X-A":"AA","X-M":["AA","two"]},"transformers":["response-template"]}`},
{"jsonBody", `{"jsonBody":{"v":"{{request.query.a}}"},` + tpl + `}`, `{"status":200,"body":"{\"v\":\"AA\"}","transformers":["response-template"]}`},
{"jsonBody unrendered", `{"jsonBody":{"v":1},` + tpl + `}`, `{"status":200,"jsonBody":{"v":1},"transformers":["response-template"]}`},
{"bodyFileName", `{"bodyFileName":"t.txt",` + tpl + `}`, `{"status":200,"body":"File AA","transformers":["response-template"]}`},
{"bodyFileName unrendered", `{"bodyFileName":"s.txt",` + tpl + `}`, `{"status":200,"bodyFileName":"s.txt","transformers":["response-template"]}`},
{"file templating disabled", `{"bodyFileName":"t.txt",` + tpl + `,"transformerParameters":{"disableBodyFileTemplating":true}}`, `{"status":200,"bodyFileName":"t.txt","transformers":["response-template"],"transformerParameters":{"disableBodyFileTemplating":true}}`},
{"not templated", `{"body":"Hi {{request.query.a}}"}`, `{"status":200,"body":"Hi {{request.query.a}}"}`},
{"execution error", `{"body":"{{math 1 '/' 0}}",` + tpl + `}`, `{"status":500,"body":"[ERROR] 1:2: java.lang.ArithmeticException: / by zero","headers":{"Content-Type":"text/plain"}}`},
} {
mapping := `{"id":"7d5a1f5e-0000-4000-8000-000000000001","request":{"urlPath":"/p"},"response":` + c.response + `}`
s.Store.ResetMappings()
s.Store.ResetRequests()
if _, err := s.Store.AddMappingDocument([]byte(mapping)); err != nil {
t.Fatal(c.name, err)
}
s.ServeHTTP(httptest.NewRecorder(), httptest.NewRequest("GET", "/p?a=AA", nil))
w := httptest.NewRecorder()
s.ServeHTTP(w, httptest.NewRequest("GET", "/__admin/requests", nil))
var journal struct {
Requests []struct {
ResponseDefinition json.RawMessage `json:"responseDefinition"`
} `json:"requests"`
}
if err := json.Unmarshal(w.Body.Bytes(), &journal); err != nil || len(journal.Requests) != 1 {
t.Fatal(c.name, err, w.Body.String())
}
var got, want any
json.Unmarshal(journal.Requests[0].ResponseDefinition, &got)
json.Unmarshal([]byte(c.want), &want)
if !reflect.DeepEqual(got, want) {
t.Errorf("%s: responseDefinition %s, want %s", c.name, journal.Requests[0].ResponseDefinition, c.want)
}
}
}
5 changes: 4 additions & 1 deletion pkg/breakmock/recording.go
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,10 @@ func (a *adminHandler) snapshot(entries []journalEntry, spec map[string]any) (ma
if len(rh) > 0 {
response["headers"] = rh
}
bodyBytes, _ := logged["bodyAsBase64"].(journalBase64)
var bodyBytes []byte
if view, ok := logged["bodyAsBase64"].(journalBase64); ok {
bodyBytes = journalBody(view).bytes()
}
if encoded, ok := logged["bodyAsBase64"].(string); ok {
bodyBytes, _ = base64.StdEncoding.DecodeString(encoded)
}
Expand Down
84 changes: 72 additions & 12 deletions pkg/breakmock/server.go
Original file line number Diff line number Diff line change
Expand Up @@ -170,7 +170,14 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
finished = time.Now()
}
req.ProcessTimeMillis = max(int64(0), (finished.Sub(processStarted) - waited).Milliseconds())
eventID = s.Store.recordServed(req, selected, capture.status, capture.Header(), capture.body.Bytes(), capture.headerOrder)
headers := capture.Header()
if len(capture.unloggedHeaders) > 0 {
headers = headers.Clone()
for _, name := range capture.unloggedHeaders {
headers.Del(name)
}
}
eventID = s.Store.recordServed(req, selected, capture.status, headers, capture.body.Bytes(), capture.headerOrder)
}
if selected != nil {
DispatchWebhooks(s.Store, eventID, req, selected, s.options.RootDir)
Expand Down Expand Up @@ -291,19 +298,36 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
}
return RenderTemplate(v, req, params)
}
var renderedHeaders map[string]any
if headers, ok := response["headers"].(map[string]any); ok {
if templated && capture != nil {
// Journaled only: WireMock logs the definition after templating.
renderedHeaders = make(map[string]any, len(headers))
}
for name, value := range headers {
values := bmSlice(value)
if values == nil {
scalar := values == nil
if scalar {
values = []any{value}
}
var renderedValues []any
for _, item := range values {
v, e := render(fmt.Sprint(item))
if e != nil {
s.writeTemplateError(w, e, selected)
s.writeTemplateError(w, e, selected, &req)
return
}
w.Header().Add(name, v)
if renderedHeaders != nil {
if scalar {
renderedHeaders[name] = v
} else {
renderedValues = append(renderedValues, v)
}
}
}
if renderedHeaders != nil && !scalar {
renderedHeaders[name] = renderedValues
}
}
}
Expand All @@ -313,7 +337,7 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if base := bmString(response["proxyBaseUrl"]); base != "" {
base, err = render(base)
if err != nil {
s.writeTemplateError(w, err, selected)
s.writeTemplateError(w, err, selected, &req)
return
}
if templated {
Expand All @@ -332,7 +356,7 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
for _, value := range values {
v, e := render(fmt.Sprint(value))
if e != nil {
s.writeTemplateError(w, e, selected)
s.writeTemplateError(w, e, selected, &req)
return
}
rendered = append(rendered, v)
Expand Down Expand Up @@ -387,29 +411,34 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if errors.As(err, &entityError) {
writeJettyError(w, r, 500, entityError.Error())
} else {
s.writeTemplateError(w, err, selected)
s.writeTemplateError(w, err, selected, &req)
}
return
}
entity.data = out
disableFileTemplate := params["disableBodyFileTemplating"] == true && entity.fromFile
rendered := false
renderedBody := ""
if templated && !disableFileTemplate {
source, e := entity.text()
if e != nil {
s.writeTemplateError(w, e, selected)
s.writeTemplateError(w, e, selected, &req)
return
}
if strings.Contains(source, "{{") {
v, e := render(source)
if e != nil {
s.writeTemplateError(w, e, selected)
s.writeTemplateError(w, e, selected, &req)
return
}
out = readOnlyBytes(v)
rendered = true
renderedBody = v
}
}
if templated && capture != nil {
req.ResponseDefinition = renderedDefinition(response, renderedHeaders, rendered, renderedBody)
}
// Avoid Go's automatic content sniffing; WireMock does not infer a type for inline bodies.
if _, ok := w.Header()["Content-Type"]; !ok {
w.Header()["Content-Type"] = nil
Expand All @@ -428,6 +457,7 @@ func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
out = compressed
w.Header().Set("Content-Encoding", "gzip")
w.Header().Del("Content-Length")
req.ResponseGzipped = true
}
w.Header().Set("Matched-Stub-Id", bmString(selected["id"]))
if name := bmString(selected["name"]); name != "" {
Expand Down Expand Up @@ -595,9 +625,12 @@ type servedResponseWriter struct {
http.ResponseWriter
startedSending time.Time
headerOrder []string
status int
wroteHeader bool
body bytes.Buffer
// unloggedHeaders are transport headers written for the client that
// WireMock's journal does not record.
unloggedHeaders []string
status int
wroteHeader bool
body bytes.Buffer
}

func (w *servedResponseWriter) WriteHeader(code int) {
Expand Down Expand Up @@ -720,9 +753,16 @@ func gzipResponseAllowed(request *http.Request, status int, headers http.Header)
return true
}

func (s *Server) writeTemplateError(w http.ResponseWriter, err error, m Mapping) {
// writeTemplateError serves a template failure. For an execution error, WireMock
// journals the error response itself as the response definition.
func (s *Server) writeTemplateError(w http.ResponseWriter, err error, m Mapping, req *Request) {
var templateError *TemplateExecutionError
if errors.As(err, &templateError) {
req.ResponseDefinition = map[string]any{"status": 500, "body": "[ERROR] " + templateError.Error(), "headers": map[string]any{"Content-Type": "text/plain"}}
if capture, ok := w.(*servedResponseWriter); ok {
capture.headerOrder = []string{"Content-Type"}
capture.unloggedHeaders = []string{"Connection"}
}
w.Header().Set("Content-Type", "text/plain")
w.Header().Set("Connection", "close")
if id := bmString(m["id"]); id != "" {
Expand All @@ -734,3 +774,23 @@ func (s *Server) writeTemplateError(w http.ResponseWriter, err error, m Mapping)
}
http.Error(w, err.Error(), 500)
}

// renderedDefinition is the response definition after templating, as WireMock
// journals it: headers rendered, and a body that was rendered replaces the stub's
// body, jsonBody or bodyFileName with the rendered text. Other fields are kept.
func renderedDefinition(response map[string]any, headers map[string]any, bodyRendered bool, body string) map[string]any {
definition := make(map[string]any, len(response))
for k, v := range response {
definition[k] = v
}
if headers != nil {
definition["headers"] = headers
}
if bodyRendered {
delete(definition, "jsonBody")
delete(definition, "bodyFileName")
delete(definition, "base64Body")
definition["body"] = body
}
return definition
}
Loading
Loading