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

# Google API CustomHttpPattern Configuration

This sample demonstrates how to configure and use `CustomHttpPattern` from `google.golang.org/genproto/googleapis/api/annotations` (pinned to `v0.0.0-20241007155032-5fefd90f89a9`).

## Background

`CustomHttpPattern` corresponds to the `google.api.CustomHttpPattern` protobuf message defined in `google/api/http.proto`. It defines custom HTTP verbs and URL path patterns for gRPC-to-JSON transcoding rules when standard HTTP methods (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) do not fit the API operation semantics (such as `:batchGet`, `:move`, or `:cancel`).

## Key Behaviors

1. **Kind and Path Specification**: Represents a custom verb (`Kind`) and path template (`Path`), accessible via direct field access or `GetKind()` and `GetPath()` getters.
2. **Nil Safety**: Calling `GetKind()` and `GetPath()` on a `nil` `*CustomHttpPattern` safely returns empty strings without triggering a nil pointer panic.
3. **Protobuf & JSON Serialization**: Supports standard protobuf binary serialization (`proto.Marshal`/`proto.Unmarshal`) and JSON serialization (`protojson.Marshal`/`protojson.Unmarshal`).
4. **HttpRule Integration**: Embeds into `HttpRule` through the `HttpRule_Custom` pattern oneof wrapper, queryable via `rule.GetCustom()`.

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.CustomHttpPattern 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.CustomHttpPattern

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:eb3db09e9384879f659ae5281a05387f8d73ddf32e81b98e9d67fd64494402f6","contract":["CustomHttpPattern struct fields and getter methods GetKind and GetPath return configured HTTP custom verb and URL pattern path.","GetKind and GetPath on a nil *CustomHttpPattern pointer safely return empty strings without panicking.","Protobuf binary serialization and deserialization preserves CustomHttpPattern Kind and Path fields exactly.","Protobuf JSON serialization produces valid JSON representation and unmarshals back to an identical CustomHttpPattern instance.","Embedding CustomHttpPattern in HttpRule.Pattern as HttpRule_Custom allows retrieving the custom verb and path via GetCustom.","Reset clears CustomHttpPattern fields back to their zero default values."],"goal":"verify google.golang.org/genproto/googleapis/api/annotations.CustomHttpPattern 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.CustomHttpPattern"]},"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.CustomHttpPattern"],"verifierAdapter":"golang@1"}

module example.com/customhttppattern

go 1.22.0

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

github.com/google/go-cmp v0.5.5 h1:Khx7svrCpmxxtHBq5j2mp/xVjsi8hQMfNLvJFAlrGgU=
github.com/google/go-cmp v0.5.5/go.mod h1:v8dTdLbMG2kIc/vJvl+f65V22dbkXbowE6jgT/gNBxE=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543 h1:E7g+9GITq07hpfrRu66IVDexMakfv52eLZ2CXBWiKr4=
golang.org/x/xerrors v0.0.0-20191204190536-9bdfabe68543/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
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"

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

func main() {
	// Create a custom HTTP pattern for a custom verb such as batchGet
	customPattern := &annotations.CustomHttpPattern{
		Kind: "BATCH_GET",
		Path: "/v1/books:batchGet",
	}

	fmt.Printf("Custom HTTP Pattern - Kind: %s, Path: %s\n", customPattern.GetKind(), customPattern.GetPath())

	// Embed into an HttpRule
	rule := &annotations.HttpRule{
		Selector: "google.example.v1.BookService.BatchGetBooks",
		Pattern: &annotations.HttpRule_Custom{
			Custom: customPattern,
		},
		Body: "*",
	}

	if custom := rule.GetCustom(); custom != nil {
		fmt.Printf("Rule %s uses custom verb %s on path %s\n", rule.GetSelector(), custom.GetKind(), custom.GetPath())
	}

	// Protobuf JSON serialization
	jsonBytes, err := protojson.Marshal(customPattern)
	if err != nil {
		fmt.Printf("JSON marshal error: %v\n", err)
		return
	}
	fmt.Printf("Serialized JSON: %s\n", string(jsonBytes))

	// Protobuf binary serialization
	wireBytes, err := proto.Marshal(customPattern)
	if err != nil {
		fmt.Printf("Binary marshal error: %v\n", err)
		return
	}
	fmt.Printf("Serialized binary size: %d bytes\n", len(wireBytes))
}

{
  "schemaVersion": 1,
  "goal": "verify google.golang.org/genproto/googleapis/api/annotations.CustomHttpPattern 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.CustomHttpPattern"
  ]
}

package main

import (
	"fmt"
	"os"

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

func main() {
	// Assertion 1: CustomHttpPattern struct fields and getter methods return configured kind and path
	{
		pattern := &annotations.CustomHttpPattern{
			Kind: "BATCH_GET",
			Path: "/v1/resources:batchGet",
		}

		if pattern.GetKind() != "BATCH_GET" {
			fmt.Fprintf(os.Stderr, "FAIL: expected GetKind() == 'BATCH_GET', got %q\n", pattern.GetKind())
			os.Exit(1)
		}
		if pattern.GetPath() != "/v1/resources:batchGet" {
			fmt.Fprintf(os.Stderr, "FAIL: expected GetPath() == '/v1/resources:batchGet', got %q\n", pattern.GetPath())
			os.Exit(1)
		}
	}

	// Assertion 2: Nil safety — GetKind and GetPath on nil CustomHttpPattern return empty strings without panicking
	{
		var nilPattern *annotations.CustomHttpPattern
		if nilPattern.GetKind() != "" {
			fmt.Fprintf(os.Stderr, "FAIL: nil GetKind() expected empty string, got %q\n", nilPattern.GetKind())
			os.Exit(1)
		}
		if nilPattern.GetPath() != "" {
			fmt.Fprintf(os.Stderr, "FAIL: nil GetPath() expected empty string, got %q\n", nilPattern.GetPath())
			os.Exit(1)
		}
	}

	// Assertion 3: Proto binary serialization and deserialization preserves CustomHttpPattern fields exactly
	{
		orig := &annotations.CustomHttpPattern{
			Kind: "MOVE",
			Path: "/v2/folders/{folder_id}:move",
		}

		wire, err := proto.Marshal(orig)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: proto.Marshal failed: %v\n", err)
			os.Exit(1)
		}

		decoded := &annotations.CustomHttpPattern{}
		if err := proto.Unmarshal(wire, decoded); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: proto.Unmarshal failed: %v\n", err)
			os.Exit(1)
		}

		if !proto.Equal(orig, decoded) {
			fmt.Fprintf(os.Stderr, "FAIL: decoded proto message does not equal original\n")
			os.Exit(1)
		}
		if decoded.GetKind() != "MOVE" || decoded.GetPath() != "/v2/folders/{folder_id}:move" {
			fmt.Fprintf(os.Stderr, "FAIL: decoded fields mismatch: kind=%q path=%q\n", decoded.GetKind(), decoded.GetPath())
			os.Exit(1)
		}
	}

	// Assertion 4: Proto JSON serialization produces expected field names and unmarshals back to CustomHttpPattern
	{
		pattern := &annotations.CustomHttpPattern{
			Kind: "CANCEL",
			Path: "/v1/orders/{order_id}:cancel",
		}

		jsonBytes, err := protojson.Marshal(pattern)
		if err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: protojson.Marshal failed: %v\n", err)
			os.Exit(1)
		}

		unmarshaled := &annotations.CustomHttpPattern{}
		if err := protojson.Unmarshal(jsonBytes, unmarshaled); err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: protojson.Unmarshal failed: %v\n", err)
			os.Exit(1)
		}

		if unmarshaled.GetKind() != "CANCEL" || unmarshaled.GetPath() != "/v1/orders/{order_id}:cancel" {
			fmt.Fprintf(os.Stderr, "FAIL: protojson unmarshaled fields mismatch\n")
			os.Exit(1)
		}
	}

	// Assertion 5: HttpRule integration — embedding CustomHttpPattern in HttpRule_Custom is accessible via GetCustom
	{
		customPattern := &annotations.CustomHttpPattern{
			Kind: "PURGE",
			Path: "/v1/cache:purge",
		}

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

		retrieved := rule.GetCustom()
		if retrieved == nil {
			fmt.Fprintf(os.Stderr, "FAIL: rule.GetCustom() returned nil\n")
			os.Exit(1)
		}
		if retrieved.GetKind() != "PURGE" || retrieved.GetPath() != "/v1/cache:purge" {
			fmt.Fprintf(os.Stderr, "FAIL: retrieved CustomHttpPattern mismatch\n")
			os.Exit(1)
		}

		// When pattern is not Custom, GetCustom returns nil
		getRule := &annotations.HttpRule{
			Selector: "example.v1.CacheService.Get",
			Pattern: &annotations.HttpRule_Get{
				Get: "/v1/cache/item",
			},
		}
		if getRule.GetCustom() != nil {
			fmt.Fprintf(os.Stderr, "FAIL: expected nil GetCustom() for non-custom HttpRule pattern\n")
			os.Exit(1)
		}
	}

	// Assertion 6: Reset clears CustomHttpPattern fields back to default empty values
	{
		pattern := &annotations.CustomHttpPattern{
			Kind: "ACTION",
			Path: "/v1/action",
		}
		pattern.Reset()
		if pattern.GetKind() != "" || pattern.GetPath() != "" {
			fmt.Fprintf(os.Stderr, "FAIL: expected empty fields after Reset(), got kind=%q path=%q\n", pattern.GetKind(), pattern.GetPath())
			os.Exit(1)
		}
	}

	fmt.Println("PASS: google.golang.org/genproto/googleapis/api/annotations.CustomHttpPattern contract passed")
}