OpenLibrary API proxy example

.golangci.yml

@@ -65,7 +65,7 @@ issues:
     # checks from err113 are useful.
     - "err113: do not define dynamic errors.*"
   exclude-rules:
-    - path: internal/examples/.*/.*\.go
+    - path: examples/.*/.*\.go
       linters:
         - forbidigo # log.Fatal, fmt.Printf used in example programs
         - gosec

Makefile

@@ -29,17 +29,16 @@ clean: ## Delete intermediate build artifacts
 .PHONY: test
 test: build ## Run unit tests
 	$(GO) test -vet=off -race -cover ./...
-	cd internal/examples/pets && $(GO) test -vet=off -race -cover ./...
-	cd internal/examples/connect+grpc && $(GO) test -vet=off -race -cover ./...
+	cd examples/pets && $(GO) test -vet=off -race -cover ./...
+	cd examples/connect+grpc && $(GO) test -vet=off -race -cover ./...
 
 .PHONY: build
 build: generate ## Build all packages
 	$(GO) build ./...
 
 .PHONY: generate
 generate: $(BIN)/buf $(BIN)/license-header ## Regenerate code and licenses
-	$(BIN)/buf generate internal/proto
-	cd internal/examples/pets && ../../../$(BIN)/buf generate internal/proto
+	$(BIN)/buf generate
 	@# We want to operate on a list of modified and new files, excluding
 	@# deleted and ignored files. git-ls-files can't do this alone. comm -23 takes
 	@# two files and prints the union, dropping lines common to both (-3) and

README.md

@@ -12,7 +12,7 @@ between gRPC, gRPC-Web, Connect, or REST, Vanguard has got you covered. With sup
 Google's [HTTP transcoding options](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto#L44),
 it can effortlessly translate protocols using strongly typed Protobuf definitions.
 
-[See an example in action!](internal/examples/fileserver/main.go)
+[See an example in action!](examples/fileserver/main.go)
 
 ## Why Vanguard?
 

buf.work.yaml

@@ -1,4 +1,5 @@
 version: v1
 directories:
   - internal/proto
-  - internal/examples/pets/internal/proto
+  - examples/pets/proto
+  - examples/openlibraryproxy/proto

internal/examples/connect+grpc/go.mod → examples/connect+grpc/go.mod

@@ -1,9 +1,9 @@
-module connectrpc.com/vanguard/internal/examples/connect+grpc
+module connectrpc.com/vanguard/examples/connect+grpc
 
 go 1.20
 
 // once the repo is public, we can remove this
-replace connectrpc.com/vanguard => ../../../
+replace connectrpc.com/vanguard => ../../
 
 require (
 	buf.build/gen/go/connectrpc/eliza/connectrpc/go v1.11.1-20230822171018-8b8b971d6fde.1

examples/openlibraryproxy/README.md

@@ -0,0 +1,42 @@
+# OpenLibrary Proxy
+
+Open Library proxy creates a vanguard service to serve [books.proto](./proto/openlibrary/v1/books.proto].
+
+## Demo
+
+Run the proxy server with:
+```
+go run .
+```
+
+Now we can use `buf curl` to call OpenLibrary's REST API via our newly created proxy.
+
+### Get a book
+
+```shell
+curl --location 'https://openlibrary.org/api/books?bibkeys=ISBN:0201558025,LCCN:93005405&format=json'
+```
+
+```shell
+buf curl --schema=./proto http://localhost:8080/openlibrary.v1.BooksService/GetBooks --data '{"bibkeys": "ISBN:0201558025,LCCN:93005405"}'
+```
+
+### Search for books
+
+Search currently can't translate due to duplicate field errors:
+```
+{
+   "code": "internal",
+   "message": "proto: (line 17562:5): duplicate field \"num_found\""
+}
+```
+
+```shell
+curl --location 'http://openlibrary.org/search.json?q=the%2Blord%2Bof%2Bthe%2Brings
+```
+
+```shell
+buf curl --schema=./proto http://localhost:8080/openlibrary.v1.BooksService/SearchBooks \
+    --data '{"q": "the lord of the rings"}'
+```
+

examples/openlibraryproxy/main.go

@@ -0,0 +1,106 @@
+// Copyright 2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"flag"
+	"log"
+	"net/http"
+	"net/http/httputil"
+	"net/url"
+	"os"
+	"strings"
+
+	"connectrpc.com/vanguard"
+	_ "connectrpc.com/vanguard/internal/gen/openlibrary/v1"
+)
+
+func main() {
+	flagset := flag.NewFlagSet("stripeproxy", flag.ExitOnError)
+	port := flagset.String("p", "8080", "port to serve on")
+	addr := flagset.String("url", "https://openlibrary.org", "base URL to proxy to")
+	debug := flagset.Bool("debug", false, "enable debug logging")
+	if err := flagset.Parse(os.Args[1:]); err != nil {
+		log.Fatal(err)
+	}
+
+	remote, err := url.Parse(*addr)
+	if err != nil {
+		log.Fatal(err)
+	}
+	proxy := httputil.NewSingleHostReverseProxy(remote)
+	if *debug {
+		proxy.Transport = &DebugTransport{}
+	}
+	// Create the handler for the proxy.
+	handler := http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		log.Println(r.Method, r.URL)
+		r.Host = remote.Host
+		w.Header().Set("X-Vanguard", "OpenLibrary Proxy")
+
+		// Alter the request for the OpenLibrary API implementation to
+		// ensure that all requests are JSON and use the data jscmd.
+		if strings.HasPrefix(r.URL.Path, "/api/books") {
+			// Convert all requests to JSON, and use the data jscmd.
+			values := r.URL.Query()
+			values.Set("format", "json")
+			values.Set("jscmd", "data")
+			r.URL.RawQuery = values.Encode()
+		}
+		proxy.ServeHTTP(w, r)
+	})
+
+	mux := &vanguard.Mux{
+		Protocols: []vanguard.Protocol{
+			// Convert all requests to REST.
+			vanguard.ProtocolREST,
+		},
+	}
+	// Register the OpenLibrary BooksService.
+	if err := mux.RegisterServiceByName(handler, "openlibrary.v1.BooksService"); err != nil {
+		log.Fatal(err)
+	}
+
+	// Alter the codec to use proto names for JSON.
+	mux.AddCodec(vanguard.CodecJSON, func(resolver vanguard.TypeResolver) vanguard.Codec {
+		codec := vanguard.DefaultJSONCodec(resolver)
+		codec.MarshalOptions.UseProtoNames = true
+		return codec
+	})
+
+	log.Printf("Proxy %s on HTTP port: %s\n", *addr, *port)
+	log.Fatal(http.ListenAndServe(":"+*port, mux))
+}
+
+type DebugTransport struct{}
+
+func (d *DebugTransport) RoundTrip(req *http.Request) (*http.Response, error) {
+	req.RequestURI = req.URL.String()
+	raw, err := httputil.DumpRequest(req, true)
+	if err != nil {
+		return nil, err
+	}
+	log.Println("Request:", string(raw))
+	rsp, err := http.DefaultTransport.RoundTrip(req)
+	if err != nil {
+		return nil, err
+	}
+	raw, err = httputil.DumpResponse(rsp, true)
+	if err != nil {
+		return nil, err
+	}
+	log.Println("Response:", string(raw))
+	return rsp, nil
+}