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

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 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
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: esm
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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:23fdbd6098c8567f000351a112b7975cb9c233c66ea19bdfef54c1bbc40256cc","contract":["annotations.HttpRule configures HTTP GET endpoint mapping with selector and path template","annotations.HttpRule serializes and deserializes accurately with protobuf wire format","annotations.HttpRule configures HTTP POST endpoint mapping with body parameter and custom response body","annotations.HttpRule supports additional URL bindings for alternative HTTP method and path patterns"],"goal":"verify google.golang.org/genproto/googleapis/api/annotations.HttpRule 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"]},"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"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.22

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

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/protobuf v1.35.1 h1:m3LfL6/Ca+fqnjnlqQXNpFPABW1UD7mjh8KO2mKFytA=
google.golang.org/protobuf v1.35.1/go.mod h1:9fA7Ob0pmnwhb644+1+CVWFRbNajQ6iRojtC/QF5bRE=

package main

import (
	"fmt"
	"log"

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

func main() {
	// Define a gRPC HTTP transcoding rule for a REST endpoint
	rule := &annotations.HttpRule{
		Selector: "google.example.library.v1.LibraryService.GetBook",
		Pattern: &annotations.HttpRule_Get{
			Get: "/v1/{name=publishers/*/books/*}",
		},
		AdditionalBindings: []*annotations.HttpRule{
			{
				Pattern: &annotations.HttpRule_Get{
					Get: "/v1/{name=books/*}",
				},
			},
		},
	}

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

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

	fmt.Printf("Selector: %s\n", decoded.GetSelector())
	fmt.Printf("HTTP GET Pattern: %s\n", decoded.GetGet())
	if len(decoded.GetAdditionalBindings()) > 0 {
		fmt.Printf("Additional Binding GET: %s\n", decoded.GetAdditionalBindings()[0].GetGet())
	}
}

{
  "schemaVersion": 1,
  "goal": "verify google.golang.org/genproto/googleapis/api/annotations.HttpRule 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"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "esm",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}

package main

import (
	"fmt"
	"os"

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

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

func main() {
	// 1. annotations.HttpRule configures HTTP GET endpoint mapping with selector and path template
	getRule := &annotations.HttpRule{
		Selector: "google.example.library.v1.LibraryService.GetBook",
		Pattern: &annotations.HttpRule_Get{
			Get: "/v1/{name=publishers/*/books/*}",
		},
	}
	assert(getRule.GetSelector() == "google.example.library.v1.LibraryService.GetBook", "selector must match")
	assert(getRule.GetGet() == "/v1/{name=publishers/*/books/*}", "get pattern must match")
	assert(getRule.GetPost() == "", "post pattern must be empty for get rule")

	// 2. annotations.HttpRule serializes and deserializes accurately with protobuf wire format
	data, err := proto.Marshal(getRule)
	assert(err == nil, "proto.Marshal(getRule) must succeed")
	assert(len(data) > 0, "marshaled payload must not be empty")

	var decoded annotations.HttpRule
	err = proto.Unmarshal(data, &decoded)
	assert(err == nil, "proto.Unmarshal(data) must succeed")
	assert(decoded.GetSelector() == getRule.GetSelector(), "decoded selector must match")
	assert(decoded.GetGet() == getRule.GetGet(), "decoded get pattern must match")

	// 3. annotations.HttpRule configures HTTP POST endpoint mapping with body parameter and custom response body
	postRule := &annotations.HttpRule{
		Selector: "google.example.library.v1.LibraryService.CreateBook",
		Pattern: &annotations.HttpRule_Post{
			Post: "/v1/{parent=publishers/*}/books",
		},
		Body:         "book",
		ResponseBody: "book",
	}
	assert(postRule.GetSelector() == "google.example.library.v1.LibraryService.CreateBook", "post selector must match")
	assert(postRule.GetPost() == "/v1/{parent=publishers/*}/books", "post pattern must match")
	assert(postRule.GetBody() == "book", "body mapping must match")
	assert(postRule.GetResponseBody() == "book", "response_body mapping must match")

	// 4. annotations.HttpRule supports additional URL bindings for alternative HTTP method and path patterns
	compositeRule := &annotations.HttpRule{
		Selector: "google.example.library.v1.LibraryService.UpdateBook",
		Pattern: &annotations.HttpRule_Patch{
			Patch: "/v1/{book.name=publishers/*/books/*}",
		},
		Body: "book",
		AdditionalBindings: []*annotations.HttpRule{
			{
				Pattern: &annotations.HttpRule_Put{
					Put: "/v1/{book.name=publishers/*/books/*}",
				},
				Body: "book",
			},
		},
	}
	assert(compositeRule.GetPatch() == "/v1/{book.name=publishers/*/books/*}", "patch pattern must match")
	assert(compositeRule.GetBody() == "book", "patch body must match")
	assert(len(compositeRule.GetAdditionalBindings()) == 1, "additional bindings count must be 1")
	assert(compositeRule.GetAdditionalBindings()[0].GetPut() == "/v1/{book.name=publishers/*/books/*}", "additional binding put pattern must match")
	assert(compositeRule.GetAdditionalBindings()[0].GetBody() == "book", "additional binding body must match")

	// Verify composite round-trip marshaling
	compData, err := proto.Marshal(compositeRule)
	assert(err == nil, "proto.Marshal(compositeRule) must succeed")
	var compDecoded annotations.HttpRule
	err = proto.Unmarshal(compData, &compDecoded)
	assert(err == nil, "proto.Unmarshal(compData) must succeed")
	assert(len(compDecoded.GetAdditionalBindings()) == 1, "decoded additional bindings count must be 1")
	assert(compDecoded.GetAdditionalBindings()[0].GetPut() == "/v1/{book.name=publishers/*/books/*}", "decoded additional binding put pattern must match")

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