google.golang.org/genproto/googleapis/api v0.0.0-20241007155032-5fefd90f89a9: annotations.HttpRule_Custom

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 google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom in pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9
Demonstrate these symbols/APIs:
  - google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom

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:3830e861d0e304d746924f165355443cbb8d9f7e7811035a452345a2bd923dca","contract":["HttpRule_Custom wraps CustomHttpPattern to configure custom HTTP verbs and path templates on HttpRule","HttpRule.GetCustom returns the CustomHttpPattern when HttpRule_Custom pattern is set, and nil for other patterns","CustomHttpPattern stores custom HTTP method kind and path, surviving proto wire serialization and deserialization","HttpRule with HttpRule_Custom can be attached to and retrieved from descriptorpb.MethodOptions via annotations.E_Http extension","HttpRule supports additional HTTP bindings containing HttpRule_Custom patterns for multiple custom verbs on the same RPC selector"],"goal":"verify google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom in pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9","kind":"HOW","packages":["pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9"],"schemaVersion":1,"symbols":["google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom"]},"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/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9","symbols":["google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.25.0

require (
	google.golang.org/genproto/googleapis/api v0.0.0-20241007155032-5fefd90f89a9
	google.golang.org/protobuf v1.36.12
)

github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
google.golang.org/genproto/googleapis/api v0.0.0-20241007155032-5fefd90f89a9 h1:T6rh4haD3GVYsgEfWExoCZA2o2FmbNyKpTuAxbEFPTg=
google.golang.org/genproto/googleapis/api v0.0.0-20241007155032-5fefd90f89a9/go.mod h1:wp2WsuBYj6j8wUdo3ToZsdxxixbvQNAHqVJrTgi5E5M=
google.golang.org/genproto/googleapis/api v0.0.0-20260825221802-da73d73af1c5 h1:izFU9hz7aeLI/Mi1J0991ae+xcwRLr7hTqWnB/9aIIU=
google.golang.org/genproto/googleapis/api v0.0.0-20260825221802-da73d73af1c5/go.mod h1:3LhxRw4YYkf+ylAfgaY9JlVLFKhokkCV8duhLLe7+t0=
google.golang.org/protobuf v1.36.12 h1:pJOKDDOyeXErUroCihFAd5LQuwXBSpVnKGrj5o/fwxc=
google.golang.org/protobuf v1.36.12/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=

package main

import (
	"fmt"
	"log"

	"google.golang.org/genproto/googleapis/api/annotations"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/descriptorpb"
)

func main() {
	// 1. Create a custom HTTP pattern for a batch-get operation
	customPattern := &annotations.CustomHttpPattern{
		Kind: "HEAD",
		Path: "/v1/books/{book_id}",
	}

	// 2. Wrap CustomHttpPattern in HttpRule_Custom and assign to HttpRule
	rule := &annotations.HttpRule{
		Selector: "google.example.v1.BookService.GetBookHeader",
		Pattern: &annotations.HttpRule_Custom{
			Custom: customPattern,
		},
		Body: "",
		AdditionalBindings: []*annotations.HttpRule{
			{
				Pattern: &annotations.HttpRule_Custom{
					Custom: &annotations.CustomHttpPattern{
						Kind: "OPTIONS",
						Path: "/v1/books/{book_id}",
					},
				},
			},
		},
	}

	// 3. Serialize and deserialize HttpRule
	data, err := proto.Marshal(rule)
	if err != nil {
		log.Fatalf("failed to marshal HttpRule: %v", err)
	}

	var decodedRule annotations.HttpRule
	if err := proto.Unmarshal(data, &decodedRule); err != nil {
		log.Fatalf("failed to unmarshal HttpRule: %v", err)
	}

	// 4. Attach HttpRule as a method extension in descriptorpb.MethodOptions
	methodOpts := &descriptorpb.MethodOptions{}
	proto.SetExtension(methodOpts, annotations.E_Http, &decodedRule)

	extRule := proto.GetExtension(methodOpts, annotations.E_Http).(*annotations.HttpRule)
	custom := extRule.GetCustom()

	fmt.Printf("Selector: %s\n", extRule.GetSelector())
	fmt.Printf("Custom Verb: %s, Path: %s\n", custom.GetKind(), custom.GetPath())
	fmt.Printf("Additional Bindings Count: %d\n", len(extRule.GetAdditionalBindings()))
}

{
  "schemaVersion": 1,
  "goal": "verify google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom in pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9",
  "kind": "HOW",
  "packages": [
    "pkg:golang/google.golang.org/genproto/googleapis/api@v0.0.0-20241007155032-5fefd90f89a9"
  ],
  "symbols": [
    "google.golang.org/genproto/googleapis/api/annotations.HttpRule_Custom"
  ]
}

package main

import (
	"fmt"
	"os"

	"google.golang.org/genproto/googleapis/api/annotations"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/descriptorpb"
)

func assert(condition bool, message string) {
	if !condition {
		fmt.Fprintf(os.Stderr, "Assertion failed: %s\n", message)
		os.Exit(1)
	}
}

func main() {
	// 1. HttpRule_Custom wraps CustomHttpPattern to configure custom HTTP verbs and path templates on HttpRule
	customPattern := &annotations.CustomHttpPattern{
		Kind: "HEAD",
		Path: "/v1/{name=publishers/*/books/*}",
	}
	assert(customPattern.GetKind() == "HEAD", "custom pattern kind should match HEAD")
	assert(customPattern.GetPath() == "/v1/{name=publishers/*/books/*}", "custom pattern path should match")

	rule := &annotations.HttpRule{
		Selector: "example.v1.BookService.GetBookHeader",
		Pattern: &annotations.HttpRule_Custom{
			Custom: customPattern,
		},
		Body: "*",
	}

	assert(rule.GetSelector() == "example.v1.BookService.GetBookHeader", "selector should match")
	assert(rule.GetBody() == "*", "body should match")

	// 2. HttpRule.GetCustom returns the CustomHttpPattern when HttpRule_Custom pattern is set, and nil for other patterns
	assert(rule.GetCustom() != nil, "GetCustom should not be nil for HttpRule_Custom pattern")
	assert(rule.GetCustom().GetKind() == "HEAD", "GetCustom().GetKind() should return HEAD")
	assert(rule.GetCustom().GetPath() == "/v1/{name=publishers/*/books/*}", "GetCustom().GetPath() should return matched path")
	assert(rule.GetGet() == "", "GetGet should return empty string when custom pattern is set")
	assert(rule.GetPost() == "", "GetPost should return empty string when custom pattern is set")

	getRule := &annotations.HttpRule{
		Pattern: &annotations.HttpRule_Get{
			Get: "/v1/books",
		},
	}
	assert(getRule.GetCustom() == nil, "GetCustom must return nil for standard GET pattern")

	// 3. CustomHttpPattern stores custom HTTP method kind and path, surviving proto wire serialization and deserialization
	data, err := proto.Marshal(rule)
	assert(err == nil, "proto.Marshal of HttpRule with HttpRule_Custom should succeed")
	assert(len(data) > 0, "marshaled payload should not be empty")

	var unmarshaled annotations.HttpRule
	err = proto.Unmarshal(data, &unmarshaled)
	assert(err == nil, "proto.Unmarshal of HttpRule should succeed")
	assert(unmarshaled.GetSelector() == "example.v1.BookService.GetBookHeader", "unmarshaled selector should match")
	assert(unmarshaled.GetCustom() != nil, "unmarshaled GetCustom should not be nil")
	assert(unmarshaled.GetCustom().GetKind() == "HEAD", "unmarshaled kind should match HEAD")
	assert(unmarshaled.GetCustom().GetPath() == "/v1/{name=publishers/*/books/*}", "unmarshaled path should match")
	assert(proto.Equal(rule, &unmarshaled), "unmarshaled rule should be proto.Equal to original rule")

	// 4. HttpRule with HttpRule_Custom can be attached to and retrieved from descriptorpb.MethodOptions via annotations.E_Http extension
	methodOpts := &descriptorpb.MethodOptions{}
	proto.SetExtension(methodOpts, annotations.E_Http, rule)

	assert(proto.HasExtension(methodOpts, annotations.E_Http), "methodOpts must have annotations.E_Http extension")
	retrievedExt := proto.GetExtension(methodOpts, annotations.E_Http)
	retrievedRule, ok := retrievedExt.(*annotations.HttpRule)
	assert(ok && retrievedRule != nil, "retrieved extension must be *annotations.HttpRule")
	assert(retrievedRule.GetCustom() != nil, "retrieved rule must have custom pattern")
	assert(retrievedRule.GetCustom().GetKind() == "HEAD", "retrieved custom pattern kind must be HEAD")

	// 5. HttpRule supports additional HTTP bindings containing HttpRule_Custom patterns for multiple custom verbs on the same RPC selector
	batchGetPattern := &annotations.CustomHttpPattern{
		Kind: "BATCH_GET",
		Path: "/v1/books:batchGet",
	}
	ruleWithBindings := &annotations.HttpRule{
		Selector: "example.v1.BookService.BatchOperations",
		Pattern: &annotations.HttpRule_Custom{
			Custom: batchGetPattern,
		},
		AdditionalBindings: []*annotations.HttpRule{
			{
				Pattern: &annotations.HttpRule_Custom{
					Custom: &annotations.CustomHttpPattern{
						Kind: "BATCH_UPDATE",
						Path: "/v1/books:batchUpdate",
					},
				},
			},
		},
	}

	assert(len(ruleWithBindings.GetAdditionalBindings()) == 1, "additional bindings count must be 1")
	additionalCustom := ruleWithBindings.GetAdditionalBindings()[0].GetCustom()
	assert(additionalCustom != nil, "additional binding must have custom pattern")
	assert(additionalCustom.GetKind() == "BATCH_UPDATE", "additional binding kind must be BATCH_UPDATE")
	assert(additionalCustom.GetPath() == "/v1/books:batchUpdate", "additional binding path must be /v1/books:batchUpdate")

	bindingsData, err := proto.Marshal(ruleWithBindings)
	assert(err == nil, "marshal rule with additional custom bindings should succeed")
	var unmarshaledWithBindings annotations.HttpRule
	err = proto.Unmarshal(bindingsData, &unmarshaledWithBindings)
	assert(err == nil, "unmarshal rule with additional custom bindings should succeed")
	assert(proto.Equal(ruleWithBindings, &unmarshaledWithBindings), "unmarshaled rule with bindings should be proto.Equal")

	fmt.Println("All contract assertions passed successfully.")
}