### gRPC Reflection CLI Examples

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Demonstrates how to use command-line tools like `grpcurl` and `buf curl` to interact with a gRPC service that supports reflection. These examples show how to list services, describe a specific service, and invoke methods dynamically without pre-compiled descriptors.

```bash
# List available services using grpcurl
grpcurl -plaintext localhost:8080 list

# Output:
# bvr.v1beta1.FooService
# grpc.reflection.v1.ServerReflection

# Describe the FooService
grpcurl -plaintext localhost:8080 describe bvr.v1beta1.FooService

# Call GetFoo using buf curl
buf curl \
  --protocol grpc \
  --http2-prior-knowledge \
  http://localhost:8080/bvr.v1beta1.FooService/GetFoo \
  -d '{"id": "1"}'

# Response
{
  "foo": {
    "id": "1",
    "name": "Bar"
  }
}

```

--------------------------------

### Start Tailcall GraphQL Server

Source: https://github.com/kevinmichaelchen/buf-vanguard-rest/blob/main/README.md

Command to start the Tailcall server, which generates a GraphQL API from the specified configuration file (`tailcall.graphql`). This enables querying the backend services via GraphQL.

```shell
pkgx tailcall start ./tailcall.graphql
```

--------------------------------

### Run Go Server

Source: https://github.com/kevinmichaelchen/buf-vanguard-rest/blob/main/README.md

Starts the main server application using Go. This command is typically used for local development and testing.

```shell
go run main.go
```

--------------------------------

### GraphQL Query Example

Source: https://github.com/kevinmichaelchen/buf-vanguard-rest/blob/main/README.md

An example GraphQL query to fetch a 'foo' resource with its nested 'id' and 'name'. This query would be executed against the GraphQL endpoint provided by Tailcall.

```graphql
{
  foo(input: { id: "1" }) {
    foo {
      id
      name
    }
  }
}

```

--------------------------------

### Make REST Request to Localhost

Source: https://github.com/kevinmichaelchen/buf-vanguard-rest/blob/main/README.md

Example of how to make a GET request to a local REST API endpoint running on port 8080. It demonstrates fetching data for a specific resource ('foos/1') and the expected JSON response.

```shell
$ http localhost:8080/foos/1

HTTP/1.1 200 OK
Accept-Encoding: gzip
Content-Encoding: gzip
Content-Length: 55
Content-Type: application/json
Date: Sat, 13 Jan 2024 18:28:44 GMT

{
    "foo": {
        "id": "1",
        "name": "Bar"
    }
}


```

--------------------------------

### Query Foo Resource via GraphQL API

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Shows how to query Foo resources using GraphQL, with the schema generated by Tailcall from REST endpoints. It includes the Tailcall configuration and an example GraphQL query to fetch specific fields of a Foo resource. The server is configured to listen on port 8000.

```graphql
# Query configuration in tailcall.graphql
schema
  @server(port: 8000, graphiql: true)
  @upstream(baseURL: "http://localhost:8080") {
  query: Query
}

type Query {
  foo(input: GetFooRequest!): GetFooResponse
    @http(path: "/foos/{{args.input.id}}")
}
```

```bash
# Start the Tailcall GraphQL server
tailcall start ./tailcall.graphql

# Example GraphQL query
curl -X POST http://127.0.0.1:8000/graphql \
  -H "Content-Type: application/json" \
  -d '{ 
    "query": "{ foo(input: { id: \"1\" }) { foo { id name } } }"
  }'

# Response
{
  "data": {
    "foo": {
      "foo": {
        "id": "1",
        "name": "Bar"
      }
    }
  }
}
```

--------------------------------

### REST API: Get Foo Resource

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Retrieve a Foo resource by ID using a RESTful HTTP GET request. The endpoint follows REST conventions with the resource ID as a path parameter, automatically transcoded from the underlying gRPC service by Vanguard.

```APIDOC
## GET /foos/{id}

### Description
Retrieve a Foo resource by ID.

### Method
GET

### Endpoint
/foos/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the Foo resource to retrieve.

### Request Example
```bash
curl http://localhost:8080/foos/1
```

### Response
#### Success Response (200)
- **foo** (object) - The requested Foo resource.
  - **id** (string) - The ID of the Foo resource.
  - **name** (string) - The name of the Foo resource.

#### Response Example
```json
{
  "foo": {
    "id": "1",
    "name": "Bar"
  }
}
```
```

--------------------------------

### Retrieve Foo Resource via REST API

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Demonstrates how to retrieve a Foo resource using a RESTful HTTP GET request to a specific endpoint. The ID is provided as a path parameter. This functionality is powered by Vanguard's automatic transcoding from the underlying gRPC service.

```bash
# Retrieve a Foo resource with ID "1"
curl http://localhost:8080/foos/1

# Response (200 OK)
{
  "foo": {
    "id": "1",
    "name": "Bar"
  }
}

# With httpie for cleaner output
http localhost:8080/foos/1
```

--------------------------------

### Create Foo Resource via Connect RPC

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Illustrates creating a new Foo resource using the Connect protocol, which employs standard HTTP with JSON payloads. The endpoint URL includes the fully-qualified service and method name. This method sends a POST request with the resource details.

```bash
# Create a new Foo resource
curl -v http://localhost:8080/bvr.v1beta1.FooService/CreateFoo \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
{
  "name": "MyFoo"
}
EOF

# Response
{
  "foo": {
    "id": "1",
    "name": "MyFoo"
  }
}

# Alternative using httpie
http http://localhost:8080/bvr.v1beta1.FooService/CreateFoo name="MyFoo"
```

--------------------------------

### Go Server Configuration with HTTP/2 and gRPC Reflection

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Configures a Go HTTP server with HTTP/2 support via h2c, enabling gRPC reflection and integrating Connect RPC and Vanguard handlers. It ensures graceful shutdown and allows multiple protocols on a single port. Dependencies include `golang.org/x/net/http2`, `connectrpc.com/grpcreflect`, and `connectrpc.com/vanguard`.

```go
// main.go (continued)
import (
	"errors"
	"net"
	"net/http"
	"time"

	"connectrpc.com/grpcreflect"
	"golang.org/x/net/http2"
	"golang.org/x/net/http2/h2c"
)

func main() {
	// ... service and handler setup ...

	serveMux := http.NewServeMux()
	serveMux.Handle(path, connectHandler)
	serveMux.Handle("/", internal.TraceHandler(vanguardHandler))

	// Enable gRPC reflection for CLI tools
	serveMux.Handle(
		grpcreflect.NewHandlerV1(
			grpcreflect.NewStaticReflector(connectPB.FooServiceName)))

	listener, err := net.Listen("tcp", "127.0.0.1:8080")
	if err != nil {
		log.Fatal(err)
	}

	svr := &http.Server{
		Addr:              ":http",
		Handler:           h2c.NewHandler(serveMux, &http2.Server{}),
		ReadHeaderTimeout: 15 * time.Second,
	}

	err = svr.Serve(listener)
	if err != nil && !errors.Is(err, http.ErrServerClosed) {
		log.Fatal(err)
	}
}

// Start the server
// go run main.go
// Server listens on http://127.0.0.1:8080

```

--------------------------------

### Make Connect Request to Localhost

Source: https://github.com/kevinmichaelchen/buf-vanguard-rest/blob/main/README.md

Demonstrates how to send a POST request to a Connect API endpoint on localhost:8080. It shows two methods using `curl` and `pkgx` to send JSON data for creating a 'Foo' resource.

```shell
curl -v http://localhost:8080/bvr.v1beta1.FooService/CreateFoo \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "name": "BAR"
  }
EOF
```

```shell
pkgx http http://localhost:8080/bvr.v1beta1.FooService/CreateFoo name="BAR"
```

--------------------------------

### Go Connect Service with Vanguard Transcoding

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Implements a Go service using Connect RPC handlers and Vanguard for multi-protocol transcoding. It supports gRPC over h2c (HTTP/2 without TLS) and integrates with Vanguard to handle different protocols on a single port. Dependencies include Connect RPC and Vanguard libraries.

```go
// main.go
package main

import (
	"context"
	"net/http"

	connectGo "connectrpc.com/connect"
	"connectrpc.com/vanguard"
	v1beta1 "github.com/kevinmichaelchen/buf-vanguard-rest/internal/idl/bvr/v1beta1"
	connectPB "github.com/kevinmichaelchen/buf-vanguard-rest/internal/idl/bvr/v1beta1/bvrv1beta1connect"
)

type fooService struct{}

func (s fooService) CreateFoo(
	_ context.Context,
	req *connectGo.Request[v1beta1.CreateFooRequest],
) (*connectGo.Response[v1beta1.CreateFooResponse], error) {
	return connectGo.NewResponse(
		&v1beta1.CreateFooResponse{
			Foo: &v1beta1.Foo{
				Id:   "1",
				Name: req.Msg.GetName(),
			},
		},
	), nil
}

func (s fooService) GetFoo(
	_ context.Context,
	req *connectGo.Request[v1beta1.GetFooRequest],
) (*connectGo.Response[v1beta1.GetFooResponse], error) {
	return connectGo.NewResponse(
		&v1beta1.GetFooResponse{
			Foo: &v1beta1.Foo{
				Id:   req.Msg.GetId(),
				Name: "Bar",
			},
		},
	), nil
}

func main() {
	path, connectHandler := connectPB.NewFooServiceHandler(&fooService{})

	// Wrap with Vanguard for multi-protocol support
	vanguardHandler, _ := vanguard.NewTranscoder(
		[]*vanguard.Service{
			vanguard.NewService(connectPB.FooServiceName, connectHandler),
		},
	)

	serveMux := http.NewServeMux()
	serveMux.Handle(path, connectHandler)
	serveMux.Handle("/", vanguardHandler)

	http.ListenAndServe(":8080", serveMux)
}

```

--------------------------------

### Connect RPC: Create Foo Resource

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Create a new Foo resource using the Connect protocol, which uses standard HTTP with JSON payloads. This endpoint follows Connect's convention of using the fully-qualified service and method name in the URL path.

```APIDOC
## POST /bvr.v1beta1.FooService/CreateFoo

### Description
Create a new Foo resource using the Connect protocol.

### Method
POST

### Endpoint
/bvr.v1beta1.FooService/CreateFoo

### Parameters
#### Request Body
- **name** (string) - Required - The name for the new Foo resource.

### Request Example
```json
{
  "name": "MyFoo"
}
```

### Response
#### Success Response (200)
- **foo** (object) - The newly created Foo resource.
  - **id** (string) - The ID of the created Foo resource.
  - **name** (string) - The name of the created Foo resource.

#### Response Example
```json
{
  "foo": {
    "id": "1",
    "name": "MyFoo"
  }
}
```
```

--------------------------------

### Protocol Buffer Service Definition for FooService

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Defines the core `FooService` using Protocol Buffers, including messages for requests and responses, and utilizes Google API annotations for REST mappings. This definition serves as the single source of truth for all API protocols supported by the project.

```protobuf
// bvr/v1beta1/api.proto
syntax = "proto3";

package bvr.v1beta1;

import "google/api/annotations.proto";

service FooService {
  rpc CreateFoo(CreateFooRequest) returns (CreateFooResponse) {}

  rpc GetFoo(GetFooRequest) returns (GetFooResponse) {
    option (google.api.http).get = "/foos/{id}";
  }

  rpc ListFoos(ListFoosRequest) returns (ListFoosResponse) {}

  rpc DeleteFoo(DeleteFooRequest) returns (DeleteFooResponse) {}
}

message Foo {
  string id = 1;
  string name = 2;
}

message CreateFooRequest {
  string name = 1;
}

message CreateFooResponse {
  Foo foo = 1;
}

message GetFooRequest {
  string id = 1;
}

message GetFooResponse {
  Foo foo = 1;
}
```

--------------------------------

### Go HTTP Request Tracing Middleware

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Provides HTTP middleware in Go for tracing incoming requests and responses. It assigns unique IDs to requests and logs details like headers and bodies, useful for debugging protocol transcoding. Relies on `net/http` and atomic operations for ID generation.

```go
// internal/trace.go
package internal

import (
	"context"
	"net/http"
	"sync/atomic"
)

var idSource atomic.Int64

func TraceHandler(handler http.Handler) http.Handler {
	return http.HandlerFunc(func(responseWriter http.ResponseWriter, request *http.Request) {
		reqID := idSource.Add(1)
		trc := &tracer{reqID: reqID}

		// Trace incoming request
		trc.traceReq("%s %s://%s%s %s",
			request.Method,
			"http",
			request.Host,
			request.URL.Path,
			request.Proto)

		// Wrap request body and response writer for tracing
		request.Body = &traceReader{r: request.Body, trace: trc.traceReq}
		request = request.WithContext(
			context.WithValue(request.Context(), traceRequestID{}, reqID))
		tw := &traceWriter{w: responseWriter, trace: trc.traceResp}

		handler.ServeHTTP(tw, request)
	})
}

// Example trace output:
// #0001>> GET http://localhost:8080/foos/1 HTTP/1.1
// #0001>> Accept: */*
// #0001>>
// #0001<< 200 OK
// #0001<< Content-Type: application/json
// #0001<< (42 bytes)

```

--------------------------------

### GraphQL API: Query Foo Resource

Source: https://context7.com/kevinmichaelchen/buf-vanguard-rest/llms.txt

Query Foo resources using GraphQL, which is generated from the REST endpoints using Tailcall. The GraphQL schema provides a unified interface with type-safe queries and selective field retrieval.

```APIDOC
## GraphQL Endpoint

### Description
Query Foo resources using GraphQL.

### Method
POST

### Endpoint
/graphql (on port 8000)

### Parameters
#### Request Body
- **query** (string) - Required - The GraphQL query string.

### Request Example
```json
{
  "query": "{ foo(input: { id: \"1\" }) { foo { id name } } }"
}
```

### Response
#### Success Response (200)
- **data** (object) - The result of the GraphQL query.

#### Response Example
```json
{
  "data": {
    "foo": {
      "foo": {
        "id": "1",
        "name": "Bar"
      }
    }
  }
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.