refactor: namings, fields, clarity, comments, documentation

- Improve documentation of public API that to conform with pkg.go.dev
  stylings. Can be previewed with:
    `go install golang.org/x/pkgsite/cmd/pkgsite@latest && pkgsite`
    Note that there's a bug that makes the comments in struct fields not
    formatted: golang/go#56004
- Renamed a few things for consistency and clarity:
    - `BlocksGateway` to `BlocksBackend` (it is an `IPFSBackend`)
    - `api` to `backend` (it is an `IPFSBackend`)
    - `WithHostname` to `NewHostnameHandler`
    - `Specification` to `PublicGateway`
    - `ErrorResponse` to `ErrorStatusCode`
    - `DagEntityByteRange` to `DagByteRange` (there isn't other)
- Unexported `ServeContent`, which was never meant to be public
- Removed `webRequestError`, which is already handled by `webError`.
  Added a test to ensure that is the case.
- Removed return types from functions that always returned nil.
- Exported `DagScopeEntity`, `DagScopeAll`, `DagScopeBlock` as they are `DagScope`
- Change some usages of global `log` variable to request-scoped `logger` for more context
- Handle CAR before maybe resolving path (CAR handles it differently)
- Response formats as constants (avoids typos, etc)

examples/gateway/car/main.go

@@ -41,12 +41,12 @@ func main() {
 	defer f.Close()
 
 	// Creates the gateway API with the block service.
-	gwAPI, err := gateway.NewBlocksGateway(blockService)
+	backend, err := gateway.NewBlocksBackend(blockService)
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	handler := common.NewHandler(gwAPI)
+	handler := common.NewHandler(backend)
 
 	log.Printf("Listening on http://localhost:%d", *port)
 	log.Printf("Metrics available at http://127.0.0.1:%d/debug/metrics/prometheus", *port)

examples/gateway/car/main_test.go

@@ -23,13 +23,13 @@ func newTestServer() (*httptest.Server, io.Closer, error) {
 		return nil, nil, err
 	}
 
-	gateway, err := gateway.NewBlocksGateway(blockService)
+	backend, err := gateway.NewBlocksBackend(blockService)
 	if err != nil {
 		_ = f.Close()
 		return nil, nil, err
 	}
 
-	handler := common.NewHandler(gateway)
+	handler := common.NewHandler(backend)
 	ts := httptest.NewServer(handler)
 	return ts, f, nil
 }

examples/gateway/common/handler.go

@@ -29,7 +29,7 @@ func NewHandler(gwAPI gateway.IPFSBackend) http.Handler {
 		// if you're running multiple public gateways on different hostnames
 		// and want different settings such as support for Deserialized
 		// Responses on localhost, or DNSLink and Subdomain Gateways.
-		PublicGateways: map[string]*gateway.Specification{
+		PublicGateways: map[string]*gateway.PublicGateway{
 			// Support public requests with Host: CID.ipfs.example.net and ID.ipns.example.net
 			"example.net": {
 				Paths:         []string{"/ipfs", "/ipns"},
@@ -80,7 +80,7 @@ func NewHandler(gwAPI gateway.IPFSBackend) http.Handler {
 	// or example.net. If you want to expose the metrics on such gateways,
 	// you will have to add the path "/debug" to the variable Paths.
 	var handler http.Handler
-	handler = gateway.WithHostname(conf, gwAPI, mux)
+	handler = gateway.NewHostnameHandler(conf, gwAPI, mux)
 
 	// Then, wrap with the withConnect middleware. This is required since we use
 	// http.ServeMux which does not support CONNECT by default.

examples/gateway/proxy/main.go

@@ -44,12 +44,12 @@ func main() {
 	routing := newProxyRouting(*gatewayUrlPtr, nil)
 
 	// Creates the gateway with the block service and the routing.
-	gwAPI, err := gateway.NewBlocksGateway(blockService, gateway.WithValueStore(routing))
+	backend, err := gateway.NewBlocksBackend(blockService, gateway.WithValueStore(routing))
 	if err != nil {
 		log.Fatal(err)
 	}
 
-	handler := common.NewHandler(gwAPI)
+	handler := common.NewHandler(backend)
 
 	log.Printf("Listening on http://localhost:%d", *port)
 	log.Printf("Try loading an image: http://localhost:%d/ipfs/bafybeigdyrzt5sfp7udm7hu76uh7y26nf3efuylqabf3oclgtqy55fbzdi", *port)

examples/gateway/proxy/main_test.go

@@ -29,12 +29,12 @@ func newProxyGateway(t *testing.T, rs *httptest.Server) *httptest.Server {
 	blockService := blockservice.New(blockStore, exch)
 	routing := newProxyRouting(rs.URL, nil)
 
-	gw, err := gateway.NewBlocksGateway(blockService, gateway.WithValueStore(routing))
+	backend, err := gateway.NewBlocksBackend(blockService, gateway.WithValueStore(routing))
 	if err != nil {
 		t.Error(err)
 	}
 
-	handler := common.NewHandler(gw)
+	handler := common.NewHandler(backend)
 	ts := httptest.NewServer(handler)
 	t.Cleanup(ts.Close)
 

gateway/README.md

@@ -4,11 +4,15 @@
 
 ## Documentation
 
-* Go Documentation: https://pkg.go.dev/github.com/ipfs/boxo/gateway
-* Gateway Specification: https://github.com/ipfs/specs/tree/main/http-gateways#readme
-* Types of HTTP Gateways: https://docs.ipfs.tech/how-to/address-ipfs-on-web/#http-gateways
+- Go Documentation: https://pkg.go.dev/github.com/ipfs/boxo/gateway
+- Gateway Specification: https://specs.ipfs.tech/
+- Types of HTTP Gateways: https://docs.ipfs.tech/how-to/address-ipfs-on-web/#http-gateways
+
 ## Example
 
+This example shows how you can start your own gateway, assuming you have an `IPFSBackend`
+implementation.
+
 ```go
 // Initialize your headers and apply the default headers.
 headers := map[string][]string{}
@@ -18,15 +22,15 @@ conf := gateway.Config{
   Headers:  headers,
 }
 
-// Initialize a NodeAPI interface for both an online and offline versions.
+// Initialize an IPFSBackend interface for both an online and offline versions.
 // The offline version should not make any network request for missing content.
-ipfs := ...
+ipfsBackend := ...
 
 // Create http mux and setup path gateway handler.
 mux := http.NewServeMux()
-gwHandler := gateway.NewHandler(conf, ipfs)
-mux.Handle("/ipfs/", gwHandler)
-mux.Handle("/ipns/", gwHandler)
+handler := gateway.NewHandler(conf, ipfsBackend)
+mux.Handle("/ipfs/", handler)
+mux.Handle("/ipns/", handler)
 
 // Start the server on :8080 and voilá! You have a basic IPFS gateway running
 // in http://localhost:8080.