github.com/grpc-ecosystem/grpc-gateway v1.16.0: runtime.DefaultHeaderMatcher, runtime.JSONBuiltin, runtime.NewPattern

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:73be1bad5af14e0dd156ea1c160691b3c16c724ea8a8ae3e73abf37d2a679713","contract":["runtime.NewPattern(1, ops, pool, \"checkout\") compiles \"/v1/books/{book_id=*}:checkout\", Pattern.Match extracts map[\"book_id\":\"bk-101\"], missing verb returns runtime.ErrNotMatch, and unsupported version != 1 returns runtime.ErrInvalidPattern","runtime.JSONBuiltin Marshal/Unmarshal and NewEncoder/NewDecoder round-trip JSON structs with ContentType() == \"application/json\"","runtime.NewServeMux().Handle(\"POST\", pat, handler) dispatches matching POST requests with HTTP 200 and pathParams, returns HTTP 405 Method Not Allowed for non-matching methods on a registered pattern, and returns HTTP 404 Not Found for unregistered paths","runtime.DefaultHeaderMatcher translates \"Grpc-Metadata-X-Request-Id\" to (\"X-Request-Id\", true), \"Authorization\" to (\"grpcgateway-Authorization\", true), and unmapped headers to (\"\", false)","utilities.NewDoubleArray constructs a prefix double-array trie where HasCommonPrefix returns true for sequences sharing a registered prefix and false otherwise"],"goal":"verify pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0","kind":"HOW","packages":["pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0"],"schemaVersion":1,"symbols":["runtime.DefaultHeaderMatcher","runtime.JSONBuiltin","runtime.NewPattern","runtime.NewServeMux","utilities.NewDoubleArray"]},"contractCommand":["go","run","./test"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0","symbols":["runtime.DefaultHeaderMatcher","runtime.JSONBuiltin","runtime.NewPattern","runtime.NewServeMux","utilities.NewDoubleArray"],"verifierAdapter":"golang@1"}

module sample

go 1.21

require github.com/grpc-ecosystem/grpc-gateway v1.16.0

require (
	github.com/golang/protobuf v1.3.3 // indirect
	google.golang.org/genproto v0.0.0-20200513103714-09dca8ec2884 // indirect
	google.golang.org/grpc v1.33.1 // indirect
)

cloud.google.com/go v0.26.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
cloud.google.com/go v0.34.0/go.mod h1:aQUYkXzVsufM+DwF1aE+0xfcU+56JwCaLick0ClmMTw=
github.com/BurntSushi/toml v0.3.1/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
github.com/antihax/optional v1.0.0/go.mod h1:uupD/76wgC+ih3iEmQUL+0Ugr19nfwCT1kdvxnR2qWY=
github.com/census-instrumentation/opencensus-proto v0.2.1/go.mod h1:f6KPmirojxKA12rnyqOA5BBL4O983OfeGPqjHWSTneU=
github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
github.com/cncf/udpa/go v0.0.0-20191209042840-269d4d468f6f/go.mod h1:M8M6+tZqaGXZJjfX53e64911xZQV5JYwmTeXPW+k8Sc=
github.com/envoyproxy/go-control-plane v0.9.0/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
github.com/envoyproxy/go-control-plane v0.9.1-0.20191026205805-5f8ba28d4473/go.mod h1:YTl/9mNaCwkRvm6d1a2C3ymFceY/DCBVvsKhRF0iEA4=
github.com/envoyproxy/go-control-plane v0.9.4/go.mod h1:6rpuAdCZL397s3pYoYcLgu1mIlRU8Am5FuJP05cCM98=
github.com/envoyproxy/protoc-gen-validate v0.1.0/go.mod h1:iSmxcyjqTsJpI2R4NaDN7+kN2VEUnK/pcBlmesArF7c=
github.com/ghodss/yaml v1.0.0/go.mod h1:4dBDuWmgqj2HViK6kFavaiC9ZROes6MMH2rRYeMEF04=
github.com/golang/glog v0.0.0-20160126235308-23def4e6c14b/go.mod h1:SBH7ygxi8pfUlaOkMMuAQtPIUF8ecWP5IEl/CR7VP2Q=
github.com/golang/mock v1.1.1/go.mod h1:oTYuIxOrZwtPieC+H1uAHpcLFnEyAGVDL/k47Jfbm0A=
github.com/golang/protobuf v1.2.0/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.3.2/go.mod h1:6lQm79b+lXiMfvg/cZm0SGofjICqVBUtrP5yJMmIC1U=
github.com/golang/protobuf v1.3.3 h1:gyjaxf+svBWX08ZjK86iN9geUJF0H6gp2IRKX6Nf6/I=
github.com/golang/protobuf v1.3.3/go.mod h1:vzj43D7+SQXF/4pzW/hwtAqwc6iTitCiVSaWz5lYuqw=
github.com/google/go-cmp v0.2.0/go.mod h1:oXzfMopK8JAjlY9xF4vHSVASa0yLyX7SntLO5aqRK0M=
github.com/google/go-cmp v0.4.0 h1:xsAVV57WRhGj6kEIi8ReJzQlHHqcBYCElAvkovg3B/4=
github.com/google/go-cmp v0.4.0/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
github.com/google/uuid v1.1.2/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
github.com/grpc-ecosystem/grpc-gateway v1.16.0 h1:gmcG1KaJ57LophUzW0Hy8NmPhnMZb4M0+kPpLofRdBo=
github.com/grpc-ecosystem/grpc-gateway v1.16.0/go.mod h1:BDjrQk3hbvj6Nolgz8mAMFbcEtjT1g+wF4CSlocrBnw=
github.com/prometheus/client_model v0.0.0-20190812154241-14fe0d1b01d4/go.mod h1:xMI15A0UPsDsEKsMN9yxemIoYk6Tm2C1GtYGdfGttqA=
github.com/rogpeppe/fastuuid v1.2.0/go.mod h1:jVj6XXZzXRy/MSR5jhDC/2q6DgLz+nrA6LYCDYWNEvQ=
golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
golang.org/x/exp v0.0.0-20190121172915-509febef88a4/go.mod h1:CJ0aWSM057203Lf6IL+f9T1iT9GByDxfZKAQTCR3kQA=
golang.org/x/lint v0.0.0-20181026193005-c67002cb31c3/go.mod h1:UVdnD1Gm6xHRNCYTkRU2/jEulfH38KcIWyp/GAMgvoE=
golang.org/x/lint v0.0.0-20190227174305-5b3e6a55c961/go.mod h1:wehouNa3lNwaWXcvxsM5YxQ5yQlVC4a0KAMCusXpPoU=
golang.org/x/lint v0.0.0-20190313153728-d0100b6bd8b3/go.mod h1:6SW0HCj/g11FgYtHlgUYUwCkIfeOF89ocIRzGO/8vkc=
golang.org/x/net v0.0.0-20180724234803-3673e40ba225/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20180826012351-8a410e7b638d/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20190108225652-1e06a53dbb7e/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20190213061140-3a22650c66bd/go.mod h1:mL1N/T3taQHkDXs73rZJwtUhF3w3ftmwwsq0BUmARs4=
golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
golang.org/x/net v0.0.0-20200822124328-c89045814202 h1:VvcQYSHwXgi7W+TpUR6A9g6Up98WAHf3f/ulnJ62IyA=
golang.org/x/net v0.0.0-20200822124328-c89045814202/go.mod h1:/O7V0waA8r7cgGh81Ro3o1hOxt32SMVPicZroKQ2sZA=
golang.org/x/oauth2 v0.0.0-20180821212333-d2e6202438be/go.mod h1:N/0e6XlmueqKjAGxoOufVs8QHGRruUQn6yWY3a++T0U=
golang.org/x/oauth2 v0.0.0-20200107190931-bf48bf16ab8d/go.mod h1:gOpvHmFTYa4IltrdGE7lF6nIHvwfUNPOp7c8zoXwtLw=
golang.org/x/sync v0.0.0-20180314180146-1d60e4601c6f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20181108010431-42b317875d0f/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20181221193216-37e7f081c4d4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
golang.org/x/sys v0.0.0-20180830151530-49385e6e1522/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd h1:xhmwyvizuTgC2qz7ZlMluP20uW+C3Rm0FD/WLDX8884=
golang.org/x/sys v0.0.0-20200323222414-85ca7c5b95cd/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
golang.org/x/text v0.3.0 h1:g61tztE5qeGQ89tm6NTjjM9VPIm088od1l6aSorWRWg=
golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
golang.org/x/tools v0.0.0-20190114222345-bf090417da8b/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
golang.org/x/tools v0.0.0-20190226205152-f727befe758c/go.mod h1:9Yl7xja0Znq3iFh3HoIrodX9oNMXvdceNzlUR8zjMvY=
golang.org/x/tools v0.0.0-20190311212946-11955173bddd/go.mod h1:LCzVGOaR6xXOjkQ3onu1FJEFr0SW1gC7cKk1uF8kGRs=
golang.org/x/tools v0.0.0-20190524140312-2c0ae7006135/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
google.golang.org/appengine v1.1.0/go.mod h1:EbEs0AVv82hx2wNQdGPgUI5lhzA/G0D9YwlJXL52JkM=
google.golang.org/appengine v1.4.0/go.mod h1:xpcJRLb0r/rnEns0DIKYYv+WjYCduHsrkT7/EB5XEv4=
google.golang.org/genproto v0.0.0-20180817151627-c66870c02cf8/go.mod h1:JiN7NxoALGmiZfu7CAH4rXhgtRTLTxftemlI0sWmxmc=
google.golang.org/genproto v0.0.0-20190819201941-24fa4b261c55/go.mod h1:DMBHOl98Agz4BDEuKkezgsaosCRResVns1a3J2ZsMNc=
google.golang.org/genproto v0.0.0-20200513103714-09dca8ec2884 h1:fiNLklpBwWK1mth30Hlwk+fcdBmIALlgF5iy77O37Ig=
google.golang.org/genproto v0.0.0-20200513103714-09dca8ec2884/go.mod h1:55QSHmfGQM9UVYDPBsyGGes0y52j32PQ3BqQfXhyH3c=
google.golang.org/grpc v1.19.0/go.mod h1:mqu4LbDTu4XGKhr4mRzUsmM4RtVoemTSY81AxZiDr8c=
google.golang.org/grpc v1.23.0/go.mod h1:Y5yQAOtifL1yxbo5wqy6BxZv8vAUGQwXBOALyacEbxg=
google.golang.org/grpc v1.25.1/go.mod h1:c3i+UQWmh7LiEpx4sFZnkU36qjEYZ0imhYfXVyQciAY=
google.golang.org/grpc v1.27.0/go.mod h1:qbnxyOmOxrQa7FizSgH+ReBfzJrCY1pSN7KXBS8abTk=
google.golang.org/grpc v1.33.1 h1:DGeFlSan2f+WEtCERJ4J9GJWk15TxUi8QGagfI87Xyc=
google.golang.org/grpc v1.33.1/go.mod h1:fr5YgcSWrqhRRxogOsw7RzIpsmvOZ6IcH4kBYTpR3n0=
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
gopkg.in/yaml.v2 v2.2.3/go.mod h1:hI93XBmqTisBFMUTm0b8Fm+jr3Dg1NNxqwp+5A1VGuI=
honnef.co/go/tools v0.0.0-20190102054323-c2f93a96b099/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=
honnef.co/go/tools v0.0.0-20190523083050-ea95bdfd59fc/go.mod h1:rf3lG4BRIbNafJWhAfAdb/ePZxsR/4RtNHQocxwk9r4=

{
  "schemaVersion": 1,
  "goal": "verify pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/grpc-ecosystem/grpc-gateway@v1.16.0"
  ]
}

package main

import (
	"bytes"
	"errors"
	"fmt"
	"net/http"
	"net/http/httptest"
	"os"

	"github.com/grpc-ecosystem/grpc-gateway/runtime"
	"github.com/grpc-ecosystem/grpc-gateway/utilities"
)

type bookRecord struct {
	BookID string `json:"book_id"`
	Title  string `json:"title"`
}

func assert(cond bool, format string, args ...interface{}) {
	if !cond {
		fmt.Fprintf(os.Stderr, "contract assertion failed: "+format+"\n", args...)
		os.Exit(1)
	}
}

func main() {
	// 1. Pattern compilation and matching via runtime.NewPattern & utilities.OpCode.
	ops := []int{
		int(utilities.OpLitPush), 0,
		int(utilities.OpLitPush), 1,
		int(utilities.OpPush), 0,
		int(utilities.OpCapture), 2,
	}
	pool := []string{"v1", "books", "book_id"}
	pat, err := runtime.NewPattern(1, ops, pool, "checkout")
	assert(err == nil, "NewPattern unexpected error: %v", err)
	assert(pat.String() == "/v1/books/{book_id=*}:checkout", "unexpected Pattern.String(): %q", pat.String())
	assert(pat.Verb() == "checkout", "unexpected Pattern.Verb(): %q", pat.Verb())

	captured, err := pat.Match([]string{"v1", "books", "bk-101"}, "checkout")
	assert(err == nil && captured["book_id"] == "bk-101", "Match failed: captured=%v err=%v", captured, err)

	_, err = pat.Match([]string{"v1", "books", "bk-101"}, "")
	assert(errors.Is(err, runtime.ErrNotMatch), "expected ErrNotMatch when verb is missing, got %v", err)

	_, err = runtime.NewPattern(99, ops, pool, "")
	assert(errors.Is(err, runtime.ErrInvalidPattern), "expected ErrInvalidPattern for version 99, got %v", err)

	// 2. JSONBuiltin marshaling, unmarshaling, and stream encoding/decoding.
	marshaler := &runtime.JSONBuiltin{}
	assert(marshaler.ContentType() == "application/json", "unexpected ContentType: %q", marshaler.ContentType())

	raw, err := marshaler.Marshal(bookRecord{BookID: "bk-101", Title: "Distributed Systems"})
	assert(err == nil, "JSONBuiltin.Marshal failed: %v", err)

	var out bookRecord
	err = marshaler.Unmarshal(raw, &out)
	assert(err == nil && out.BookID == "bk-101" && out.Title == "Distributed Systems", "JSONBuiltin.Unmarshal mismatch: %+v err=%v", out, err)

	var buf bytes.Buffer
	err = marshaler.NewEncoder(&buf).Encode(bookRecord{BookID: "bk-202", Title: "RPC Guide"})
	assert(err == nil, "NewEncoder.Encode failed: %v", err)
	var streamed bookRecord
	err = marshaler.NewDecoder(&buf).Decode(&streamed)
	assert(err == nil && streamed.BookID == "bk-202", "NewDecoder.Decode failed: %+v err=%v", streamed, err)

	// 3. ServeMux HTTP routing, path parameter extraction, 405 and 404 responses.
	mux := runtime.NewServeMux()
	mux.Handle("POST", pat, func(w http.ResponseWriter, r *http.Request, pathParams map[string]string) {
		w.Header().Set("Content-Type", marshaler.ContentType())
		payload, mErr := marshaler.Marshal(bookRecord{BookID: pathParams["book_id"], Title: "CheckedOut"})
		if mErr != nil {
			http.Error(w, mErr.Error(), http.StatusInternalServerError)
			return
		}
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write(payload)
	})

	recOK := httptest.NewRecorder()
	mux.ServeHTTP(recOK, httptest.NewRequest("POST", "http://localhost/v1/books/bk-101:checkout", nil))
	assert(recOK.Code == http.StatusOK, "expected 200 OK, got %d", recOK.Code)
	var routed bookRecord
	err = marshaler.Unmarshal(recOK.Body.Bytes(), &routed)
	assert(err == nil && routed.BookID == "bk-101" && routed.Title == "CheckedOut", "unexpected routed response: %+v err=%v", routed, err)

	rec405 := httptest.NewRecorder()
	mux.ServeHTTP(rec405, httptest.NewRequest("GET", "http://localhost/v1/books/bk-101:checkout", nil))
	assert(rec405.Code == http.StatusMethodNotAllowed, "expected 405 Method Not Allowed, got %d", rec405.Code)

	rec404 := httptest.NewRecorder()
	mux.ServeHTTP(rec404, httptest.NewRequest("POST", "http://localhost/v1/unknown", nil))
	assert(rec404.Code == http.StatusNotFound, "expected 404 Not Found, got %d", rec404.Code)

	// 4. DefaultHeaderMatcher header translation rules.
	metaKey, ok := runtime.DefaultHeaderMatcher("Grpc-Metadata-X-Request-Id")
	assert(ok && metaKey == "X-Request-Id", "DefaultHeaderMatcher metadata header got (%q, %v)", metaKey, ok)

	authKey, ok := runtime.DefaultHeaderMatcher("Authorization")
	assert(ok && authKey == "grpcgateway-Authorization", "DefaultHeaderMatcher Authorization got (%q, %v)", authKey, ok)

	unmappedKey, ok := runtime.DefaultHeaderMatcher("X-Ignored-Header")
	assert(!ok && unmappedKey == "", "DefaultHeaderMatcher unmapped header got (%q, %v)", unmappedKey, ok)

	// 5. utilities.NewDoubleArray prefix lookup.
	da := utilities.NewDoubleArray([][]string{
		{"book", "author"},
		{"library", "branch"},
	})
	assert(da.HasCommonPrefix([]string{"book", "author", "name"}), "HasCommonPrefix should match book.author.name")
	assert(!da.HasCommonPrefix([]string{"reader", "id"}), "HasCommonPrefix should not match reader.id")
}