docs: Host-based examples

examples/gateway/car/README.md

@@ -1,4 +1,4 @@
-# Gateway backed by a CAR File
+# HTTP Gateway backed by a CAR File
 
 This is an example that shows how to build a Gateway backed by the contents of
 a CAR file. A [CAR file](https://ipld.io/specs/transport/car/) is a Content
@@ -7,7 +7,7 @@ Addressable aRchive that contains blocks.
 ## Build
 
 ```bash
-> go build -o gateway
+> go build -o car-gateway
 ```
 
 ## Usage
@@ -23,10 +23,19 @@ Then, you can start the gateway with:
 
 
 ```
-./gateway -c data.car -p 8040
+./car-gateway -c data.car -p 8040
 ```
 
+### Subdomain gateway
+
 Now you can access the gateway in [localhost:8040](http://localhost:8040). It will
-behave like a regular IPFS Gateway, except for the fact that all contents are provided
+behave like a regular [Subdomain IPFS Gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway),
+except for the fact that all contents are provided
 from the CAR file. Therefore, things such as IPNS resolution and fetching contents
 from nodes in the IPFS network won't work.
+
+### Path gateway
+
+If you don't need Origin isolation and only care about hosting flat files,
+a plain [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at [127.0.0.1:8040](http://127.0.0.1:8040)
+may suffice.

examples/gateway/car/main.go

@@ -18,7 +18,7 @@ import (
 
 func main() {
 	carFilePtr := flag.String("c", "", "path to CAR file to back this gateway from")
-	portPtr := flag.Int("p", 8080, "port to run this gateway from")
+	port := flag.Int("p", 8040, "port to run this gateway from")
 	flag.Parse()
 
 	blockService, roots, f, err := newBlockServiceFromCAR(*carFilePtr)
@@ -31,28 +31,35 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	handler := common.NewBlocksHandler(gwAPI, *portPtr)
+	handler := common.NewBlocksHandler(gwAPI, *port)
 
 	// Initialize the public gateways that we will want to have available through
 	// Host header rewritting. This step is optional and only required if you're
 	// running multiple public gateways and want different settings and support
 	// for DNSLink and Subdomain Gateways.
+	noDNSLink := true // If you set DNSLink to point at the CID from CAR, you can load it!
 	publicGateways := map[string]*gateway.Specification{
+		// Support public requests with Host: CID.ipfs.example.net and ID.ipns.example.net
+		"example.net": {
+			Paths:         []string{"/ipfs", "/ipns"},
+			NoDNSLink:     noDNSLink,
+			UseSubdomains: true,
+		},
+		// Support local requests
 		"localhost": {
 			Paths:         []string{"/ipfs", "/ipns"},
-			NoDNSLink:     true,
+			NoDNSLink:     noDNSLink,
 			UseSubdomains: true,
 		},
 	}
-	noDNSLink := true
 	handler = gateway.WithHostname(handler, gwAPI, publicGateways, noDNSLink)
 
-	log.Printf("Listening on http://localhost:%d", *portPtr)
+	log.Printf("Listening on http://localhost:%d", *port)
 	for _, cid := range roots {
-		log.Printf("Hosting CAR root at http://localhost:%d/ipfs/%s", *portPtr, cid.String())
+		log.Printf("Hosting CAR root at http://localhost:%d/ipfs/%s", *port, cid.String())
 	}
 
-	if err := http.ListenAndServe(":"+strconv.Itoa(*portPtr), handler); err != nil {
+	if err := http.ListenAndServe(":"+strconv.Itoa(*port), handler); err != nil {
 		log.Fatal(err)
 	}
 }

examples/gateway/proxy/README.md

@@ -28,9 +28,31 @@ types. Once you have it, run the proxy gateway with its address as the host para
 
 
 ```
-./verifying-proxy -h https://ipfs.io -p 8040
+./verifying-proxy -g https://ipfs.io -p 8040
 ```
 
+### Subdomain gateway
+
 Now you can access the gateway in [localhost:8040](http://localhost:8040). It will
-behave like a regular IPFS Gateway, except for the fact that it runs no libp2p, and has no local blockstore.
+behave like a regular [Subdomain IPFS Gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#subdomain-gateway),
+except for the fact that it runs no libp2p, and has no local blockstore.
 All contents are provided by a remote  gateway and fetched as RAW Blocks and Records, and verified locally.
+
+### Path gateway
+
+If you don't need Origin isolation and only care about hosting flat files,
+a plain [path gateway](https://docs.ipfs.tech/how-to/address-ipfs-on-web/#path-gateway) at [127.0.0.1:8040](http://127.0.0.1:8040)
+may suffice.
+
+### DNSLink gateway
+
+Gateway supports hosting of [DNSLink](https://dnslink.dev/) websites. All you need is to pass `Host` header with FQDN that has DNSLink set up:
+
+```console
+$ curl -sH 'Host: en.wikipedia-on-ipfs.org' 'http://127.0.0.1:8080/wiki/' | head -3
+<!DOCTYPE html><html class="client-js"><head>
+  <meta charset="UTF-8">
+  <title>Wikipedia, the free encyclopedia</title>
+```
+
+Put it behind a reverse proxy terminating TLS (like Nginx) and voila!

examples/gateway/proxy/main.go

@@ -14,7 +14,7 @@ import (
 
 func main() {
 	gatewayUrlPtr := flag.String("g", "", "gateway to proxy to")
-	portPtr := flag.Int("p", 8080, "port to run this gateway from")
+	port := flag.Int("p", 8040, "port to run this gateway from")
 	flag.Parse()
 
 	// Sets up the block store, which will proxy the block requests to the given gateway.
@@ -29,24 +29,31 @@ func main() {
 	if err != nil {
 		log.Fatal(err)
 	}
-	handler := common.NewBlocksHandler(gwAPI, *portPtr)
+	handler := common.NewBlocksHandler(gwAPI, *port)
 
 	// Initialize the public gateways that we will want to have available through
 	// Host header rewritting. This step is optional and only required if you're
 	// running multiple public gateways and want different settings and support
 	// for DNSLink and Subdomain Gateways.
+	noDNSLink := false
 	publicGateways := map[string]*gateway.Specification{
+		// Support public requests with Host: CID.ipfs.example.net and ID.ipns.example.net
+		"example.net": {
+			Paths:         []string{"/ipfs", "/ipns"},
+			NoDNSLink:     noDNSLink,
+			UseSubdomains: true,
+		},
+		// Support local requests
 		"localhost": {
 			Paths:         []string{"/ipfs", "/ipns"},
-			NoDNSLink:     true,
+			NoDNSLink:     noDNSLink,
 			UseSubdomains: true,
 		},
 	}
-	noDNSLink := true
 	handler = gateway.WithHostname(handler, gwAPI, publicGateways, noDNSLink)
 
-	log.Printf("Listening on http://localhost:%d", *portPtr)
-	if err := http.ListenAndServe(":"+strconv.Itoa(*portPtr), handler); err != nil {
+	log.Printf("Listening on http://localhost:%d", *port)
+	if err := http.ListenAndServe(":"+strconv.Itoa(*port), handler); err != nil {
 		log.Fatal(err)
 	}
 }

gateway/hostname.go

@@ -20,6 +20,7 @@ import (
 type Specification struct {
 	// Paths is explicit list of path prefixes that should be handled by
 	// this gateway. Example: `["/ipfs", "/ipns"]`
+	// Useful if you only want to support immutable `/ipfs`.
 	Paths []string
 
 	// UseSubdomains indicates whether or not this gateway uses subdomains
@@ -32,13 +33,17 @@ type Specification struct {
 	// for security reasons (Origin isolation).
 	UseSubdomains bool
 
-	// NoDNSLink configures this gateway to _not_ resolve DNSLink for the FQDN
-	// provided in `Host` HTTP header.
+	// NoDNSLink configures this gateway to _not_ resolve DNSLink for the
+	// specific FQDN provided in `Host` HTTP header. Useful when you want to
+	// explicitly allow or refuse hosting a single hostname. To refuse all
+	// DNSLinks in `Host` processing, pass noDNSLink to `WithHostname` instead.
+	// This flag overrides the global one.
 	NoDNSLink bool
 
 	// InlineDNSLink configures this gateway to always inline DNSLink names
 	// (FQDN) into a single DNS label in order to interop with wildcard TLS certs
 	// and Origin per CID isolation provided by rules like https://publicsuffix.org
+	// This should be set to true if you use HTTPS.
 	InlineDNSLink bool
 }