google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9: errdetails.Help

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

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

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:96818fdd8903fdf9c064e2963ee13097ae84b179b6ae1bd7266a1585f1cf7ec5","contract":["errdetails.Help initializes with Help_Link entries containing description and url","errdetails.Help serializes to and deserializes from protocol buffer wire format","errdetails.Help packs into anypb.Any and unpacks back via UnmarshalTo","status.Status includes Help details in RPC status message and preserves links"],"goal":"verify google.golang.org/genproto/googleapis/rpc/errdetails.Help in pkg:golang/google.golang.org/genproto/googleapis/rpc@v0.0.0-20241007155032-5fefd90f89a9","kind":"HOW","packages":["pkg:golang/google.golang.org/genproto/googleapis/rpc@v0.0.0-20241007155032-5fefd90f89a9"],"schemaVersion":1,"symbols":["google.golang.org/genproto/googleapis/rpc/errdetails.Help"]},"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/rpc@v0.0.0-20241007155032-5fefd90f89a9"],"schemaVersion":1,"subject":"pkg:golang/google.golang.org/genproto/googleapis/rpc@v0.0.0-20241007155032-5fefd90f89a9","symbols":["google.golang.org/genproto/googleapis/rpc/errdetails.Help"],"verifierAdapter":"golang@1"}

module example.com/sample

go 1.22

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

github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
github.com/google/go-cmp v0.5.9/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9 h1:QCqS/PdaHTSWGvupk2F/ehwHtGc0/GYkT+3GAcR1CCc=
google.golang.org/genproto/googleapis/rpc v0.0.0-20241007155032-5fefd90f89a9/go.mod h1:GX3210XPVPUjJbTUbvwI8f2IpZDMZuPJWDzDuebbviI=
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/rpc/code"
	"google.golang.org/genproto/googleapis/rpc/errdetails"
	"google.golang.org/genproto/googleapis/rpc/status"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/known/anypb"
)

func main() {
	// Create Help error detail with documentation links
	help := &errdetails.Help{
		Links: []*errdetails.Help_Link{
			{
				Description: "API troubleshooting guide",
				Url:         "https://example.com/docs/troubleshooting",
			},
			{
				Description: "RPC error code reference",
				Url:         "https://example.com/docs/errors",
			},
		},
	}

	// Pack Help detail into protobuf Any message
	anyHelp, err := anypb.New(help)
	if err != nil {
		log.Fatalf("failed to pack Help detail: %v", err)
	}

	// Create RPC status with the Help detail attached
	st := &status.Status{
		Code:    int32(code.Code_INVALID_ARGUMENT),
		Message: "request validation failed; refer to help documentation",
		Details: []*anypb.Any{anyHelp},
	}

	// Marshal Status to protobuf wire format
	data, err := proto.Marshal(st)
	if err != nil {
		log.Fatalf("failed to marshal status: %v", err)
	}

	// Unmarshal Status from wire format
	var decodedStatus status.Status
	if err := proto.Unmarshal(data, &decodedStatus); err != nil {
		log.Fatalf("failed to unmarshal status: %v", err)
	}

	fmt.Printf("Status Code: %d\n", decodedStatus.GetCode())
	fmt.Printf("Status Message: %s\n", decodedStatus.GetMessage())

	// Unpack Help detail from status
	for _, detail := range decodedStatus.GetDetails() {
		var decodedHelp errdetails.Help
		if err := detail.UnmarshalTo(&decodedHelp); err == nil {
			fmt.Printf("Help Links Count: %d\n", len(decodedHelp.GetLinks()))
			for _, link := range decodedHelp.GetLinks() {
				fmt.Printf(" - %s: %s\n", link.GetDescription(), link.GetUrl())
			}
		}
	}
}

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

package main

import (
	"fmt"
	"os"

	"google.golang.org/genproto/googleapis/rpc/code"
	"google.golang.org/genproto/googleapis/rpc/errdetails"
	"google.golang.org/genproto/googleapis/rpc/status"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/known/anypb"
)

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

func main() {
	// 1. errdetails.Help initializes with Help_Link entries containing description and url
	help := &errdetails.Help{
		Links: []*errdetails.Help_Link{
			{
				Description: "Troubleshooting Guide",
				Url:         "https://example.com/docs/troubleshooting",
			},
			{
				Description: "RPC Error Reference",
				Url:         "https://example.com/docs/errors",
			},
		},
	}
	assert(len(help.GetLinks()) == 2, "help should have 2 links")
	assert(help.GetLinks()[0].GetDescription() == "Troubleshooting Guide", "first link description should match")
	assert(help.GetLinks()[0].GetUrl() == "https://example.com/docs/troubleshooting", "first link url should match")
	assert(help.GetLinks()[1].GetDescription() == "RPC Error Reference", "second link description should match")
	assert(help.GetLinks()[1].GetUrl() == "https://example.com/docs/errors", "second link url should match")

	// 2. errdetails.Help serializes to and deserializes from protocol buffer wire format
	data, err := proto.Marshal(help)
	assert(err == nil, "proto.Marshal(help) should succeed")
	assert(len(data) > 0, "marshaled help bytes should not be empty")

	var unmarshaledHelp errdetails.Help
	err = proto.Unmarshal(data, &unmarshaledHelp)
	assert(err == nil, "proto.Unmarshal should succeed for Help")
	assert(len(unmarshaledHelp.GetLinks()) == 2, "unmarshaled help should have 2 links")
	assert(unmarshaledHelp.GetLinks()[0].GetDescription() == "Troubleshooting Guide", "unmarshaled link 0 description matches")
	assert(unmarshaledHelp.GetLinks()[0].GetUrl() == "https://example.com/docs/troubleshooting", "unmarshaled link 0 url matches")
	assert(unmarshaledHelp.GetLinks()[1].GetDescription() == "RPC Error Reference", "unmarshaled link 1 description matches")
	assert(unmarshaledHelp.GetLinks()[1].GetUrl() == "https://example.com/docs/errors", "unmarshaled link 1 url matches")

	// 3. errdetails.Help packs into anypb.Any and unpacks back via UnmarshalTo
	anyHelp, err := anypb.New(help)
	assert(err == nil, "anypb.New(help) should succeed")
	assert(anyHelp.MessageIs(&errdetails.Help{}), "anyHelp should identify as errdetails.Help")

	unpackedHelp := &errdetails.Help{}
	err = anyHelp.UnmarshalTo(unpackedHelp)
	assert(err == nil, "anyHelp.UnmarshalTo should succeed")
	assert(len(unpackedHelp.GetLinks()) == 2, "unpacked help should have 2 links")
	assert(unpackedHelp.GetLinks()[0].GetUrl() == "https://example.com/docs/troubleshooting", "unpacked url matches")

	// 4. status.Status includes Help details in RPC status message and preserves links
	st := &status.Status{
		Code:    int32(code.Code_INVALID_ARGUMENT),
		Message: "request payload contains invalid fields",
		Details: []*anypb.Any{anyHelp},
	}
	assert(st.GetCode() == int32(code.Code_INVALID_ARGUMENT), "status code should match INVALID_ARGUMENT")
	assert(len(st.GetDetails()) == 1, "status details count should be 1")

	stBytes, err := proto.Marshal(st)
	assert(err == nil, "proto.Marshal(st) should succeed")

	var unmarshaledStatus status.Status
	err = proto.Unmarshal(stBytes, &unmarshaledStatus)
	assert(err == nil, "proto.Unmarshal(st) should succeed")
	assert(len(unmarshaledStatus.GetDetails()) == 1, "unmarshaled status details count should be 1")

	extractedHelp := &errdetails.Help{}
	err = unmarshaledStatus.GetDetails()[0].UnmarshalTo(extractedHelp)
	assert(err == nil, "unmarshaling detail to extractedHelp should succeed")
	assert(len(extractedHelp.GetLinks()) == 2, "extracted help links count should be 2")
	assert(extractedHelp.GetLinks()[0].GetDescription() == "Troubleshooting Guide", "extracted help link description matches")

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