feat: add Gateway.DisableHTMLErrors option (#10137)

2025-05-17 23:16:11 +08:00 · 2023-09-21 17:03:17 +02:00
parent f46bf77c80
commit 0bac56c3aa
11 changed files with 76 additions and 11 deletions
--- a/config/gateway.go
+++ b/config/gateway.go
@ -3,6 +3,7 @@ package config
 const (
 	DefaultInlineDNSLink         = false
 	DefaultDeserializedResponses = true
+	DefaultDisableHTMLErrors     = false
 	DefaultExposeRoutingAPI      = false
 )

@ -70,6 +71,10 @@ type Gateway struct {
 	// be overridden per FQDN in PublicGateways.
 	DeserializedResponses Flag

+	// DisableHTMLErrors disables pretty HTML pages when an error occurs. Instead, a `text/plain`
+	// page will be sent with the raw error message.
+	DisableHTMLErrors Flag
+
 	// PublicGateways configures behavior of known public gateways.
 	// Each key is a fully qualified domain name (FQDN).
 	PublicGateways map[string]*GatewaySpec
--- a/core/corehttp/gateway.go
+++ b/core/corehttp/gateway.go
@ -237,6 +237,7 @@ func getGatewayConfig(n *core.IpfsNode) (gateway.Config, error) {
 	gwCfg := gateway.Config{
 		Headers:               headers,
 		DeserializedResponses: cfg.Gateway.DeserializedResponses.WithDefault(config.DefaultDeserializedResponses),
+		DisableHTMLErrors:     cfg.Gateway.DisableHTMLErrors.WithDefault(config.DefaultDisableHTMLErrors),
 		NoDNSLink:             cfg.Gateway.NoDNSLink,
 		PublicGateways:        map[string]*gateway.PublicGateway{},
 	}
--- a/docs/changelogs/v0.23.md
+++ b/docs/changelogs/v0.23.md
@ -8,6 +8,7 @@
 - [🔦 Highlights](#-highlights)
  - [Mplex deprecation](#mplex-deprecation)
  - [Gateway: meaningful CAR responses on Not Found errors](#gateway-meaningful-car-responses-on-not-found-errors)
+  - [Gateway: added `Gateway.DisableHTMLErrors` configuration option](#gateway-added-gatewaydisablehtmlerrors-configuration-option)
  - [Binary characters in file names: no longer works with old clients and new Kubo servers](#binary-characters-in-file-names-no-longer-works-with-old-clients-and-new-kubo-servers)
  - [Self-hosting `/routing/v1` endpoint for delegated routing needs](#self-hosting-routingv1-endpoint-for-delegated-routing-needs)
  - [Trustless Gateway Over Libp2p Experiment](#trustless-gateway-over-libp2p-experiment)
@ -47,6 +48,13 @@ the path does not exist, a CAR will be sent with a root of `bafkqaaa` (empty CID
 This CAR will contain all blocks necessary to validate that the path does not
 exist without having to trust the gateway.

+#### Gateway: added `Gateway.DisableHTMLErrors` configuration option
+
+The `Gateway.DisableHTMLErrors` configuration option forces errors to be
+displayed in browsers as plain text (`text/plain`) rather than HTML error
+pages. It's especially beneficial for whitelabel or middleware deployments that
+wish to avoid IPFS branding and links on error pages in browsers.
+
 #### Binary characters in file names: no longer works with old clients and new Kubo servers

 In this version, we updated Kubo to support Go 1.20+. In Go 1.20, a regression
--- a/docs/config.md
+++ b/docs/config.md
@ -51,6 +51,8 @@ config file at runtime.
    - [`Gateway.NoFetch`](#gatewaynofetch)
    - [`Gateway.NoDNSLink`](#gatewaynodnslink)
    - [`Gateway.DeserializedResponses`](#gatewaydeserializedresponses)
+    - [`Gateway.DisableHTMLErrors`](#gatewaydisablehtmlerrors)
+    - [`Gateway.ExposeRoutingAPI`](#gatewayexposeroutingapi)
    - [`Gateway.HTTPHeaders`](#gatewayhttpheaders)
    - [`Gateway.RootRedirect`](#gatewayrootredirect)
    - [`Gateway.FastDirIndexThreshold`](#gatewayfastdirindexthreshold)
@ -648,7 +650,7 @@ Default: `false`

 Type: `bool`

-#### `Gateway.DeserializedResponses`
+### `Gateway.DeserializedResponses`

 An optional flag to explicitly configure whether this gateway responds to deserialized
 requests, or not. By default, it is enabled. When disabling this option, the gateway
@ -658,12 +660,26 @@ Default: `true`

 Type: `flag`

-#### `Gateway.ExposeRoutingAPI`
+### `Gateway.DisableHTMLErrors`
+
+An optional flag to disable the pretty HTML error pages of the gateway. Instead,
+a `text/plain` page will be returned with the raw error message from Kubo.
+
+It is useful for whitelabel or middleware deployments that wish to avoid
+`text/html` responses with IPFS branding and links on error pages in browsers.
+
+Default: `false`
+
+Type: `flag`
+
+### `Gateway.ExposeRoutingAPI`

 An optional flag to expose Kubo `Routing` system on the gateway port as a [Routing
 V1](https://specs.ipfs.tech/routing/routing-v1/) endpoint.  This only affects your
 local gateway, at `127.0.0.1`.

+This endpoint can be used by other Kubo instance, as illustrated in [`delegated_routing_v1_http_proxy_test.go`](https://github.com/ipfs/kubo/blob/master/test/cli/delegated_routing_v1_http_proxy_test.go).
+
 Default: `false`

 Type: `flag`
--- a/docs/examples/kubo-as-a-library/go.mod
+++ b/docs/examples/kubo-as-a-library/go.mod
@ -7,7 +7,7 @@ go 1.20
 replace github.com/ipfs/kubo => ./../../..

 require (
-	github.com/ipfs/boxo v0.13.0
+	github.com/ipfs/boxo v0.13.1
 	github.com/ipfs/kubo v0.0.0-00010101000000-000000000000
 	github.com/libp2p/go-libp2p v0.31.0
 	github.com/multiformats/go-multiaddr v0.11.0
--- a/docs/examples/kubo-as-a-library/go.sum
+++ b/docs/examples/kubo-as-a-library/go.sum
@ -300,8 +300,8 @@ github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
 github.com/ipfs/bbloom v0.0.4 h1:Gi+8EGJ2y5qiD5FbsbpX/TMNcJw8gSqr7eyjHa4Fhvs=
 github.com/ipfs/bbloom v0.0.4/go.mod h1:cS9YprKXpoZ9lT0n/Mw/a6/aFV6DTjTLYHeA+gyqMG0=
-github.com/ipfs/boxo v0.13.0 h1:uzCQekieYS4PysbYYdodNmKLuqOdLjlUziXVZ19oDeQ=
-github.com/ipfs/boxo v0.13.0/go.mod h1:btrtHy0lmO1ODMECbbEY1pxNtrLilvKSYLoGQt1yYCk=
+github.com/ipfs/boxo v0.13.1 h1:nQ5oQzcMZR3oL41REJDcTbrvDvuZh3J9ckc9+ILeRQI=
+github.com/ipfs/boxo v0.13.1/go.mod h1:btrtHy0lmO1ODMECbbEY1pxNtrLilvKSYLoGQt1yYCk=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.0.2/go.mod h1:AWR46JfpcObNfg3ok2JHDUfdiHRgWhJgCQF+KIgOPJY=
--- a/go.mod
+++ b/go.mod
@ -15,7 +15,7 @@ require (
 	github.com/fsnotify/fsnotify v1.6.0
 	github.com/google/uuid v1.3.0
 	github.com/hashicorp/go-multierror v1.1.1
-	github.com/ipfs/boxo v0.13.0
+	github.com/ipfs/boxo v0.13.1
 	github.com/ipfs/go-block-format v0.1.2
 	github.com/ipfs/go-cid v0.4.1
 	github.com/ipfs/go-cidutil v0.1.0
--- a/go.sum
+++ b/go.sum
@ -335,8 +335,8 @@ github.com/ianlancetaylor/demangle v0.0.0-20181102032728-5e5cf60278f6/go.mod h1:
 github.com/inconshreveable/mousetrap v1.0.0/go.mod h1:PxqpIevigyE2G7u3NXJIT2ANytuPF1OarO4DADm73n8=
 github.com/ipfs/bbloom v0.0.4 h1:Gi+8EGJ2y5qiD5FbsbpX/TMNcJw8gSqr7eyjHa4Fhvs=
 github.com/ipfs/bbloom v0.0.4/go.mod h1:cS9YprKXpoZ9lT0n/Mw/a6/aFV6DTjTLYHeA+gyqMG0=
-github.com/ipfs/boxo v0.13.0 h1:uzCQekieYS4PysbYYdodNmKLuqOdLjlUziXVZ19oDeQ=
-github.com/ipfs/boxo v0.13.0/go.mod h1:btrtHy0lmO1ODMECbbEY1pxNtrLilvKSYLoGQt1yYCk=
+github.com/ipfs/boxo v0.13.1 h1:nQ5oQzcMZR3oL41REJDcTbrvDvuZh3J9ckc9+ILeRQI=
+github.com/ipfs/boxo v0.13.1/go.mod h1:btrtHy0lmO1ODMECbbEY1pxNtrLilvKSYLoGQt1yYCk=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-bitswap v0.11.0 h1:j1WVvhDX1yhG32NTC9xfxnqycqYIlhzEzLXG/cU1HyQ=
--- a/test/cli/gateway_test.go
+++ b/test/cli/gateway_test.go
@ -593,4 +593,39 @@ func TestGateway(t *testing.T) {
 			t.Run(test.message, makeTest(test))
 		}
 	})
+
+	t.Run("DisableHTMLErrors", func(t *testing.T) {
+		t.Parallel()
+
+		t.Run("Returns HTML error without DisableHTMLErrors, Accept contains text/html", func(t *testing.T) {
+			t.Parallel()
+
+			node := harness.NewT(t).NewNode().Init()
+			node.StartDaemon()
+			client := node.GatewayClient()
+
+			res := client.Get("/ipfs/invalid-thing", func(r *http.Request) {
+				r.Header.Set("Accept", "text/html")
+			})
+			assert.NotEqual(t, http.StatusOK, res.StatusCode)
+			assert.Contains(t, res.Resp.Header.Get("Content-Type"), "text/html")
+		})
+
+		t.Run("Does not return HTML error with DisableHTMLErrors enabled, and Accept contains text/html", func(t *testing.T) {
+			t.Parallel()
+
+			node := harness.NewT(t).NewNode().Init()
+			node.UpdateConfig(func(cfg *config.Config) {
+				cfg.Gateway.DisableHTMLErrors = config.True
+			})
+			node.StartDaemon()
+			client := node.GatewayClient()
+
+			res := client.Get("/ipfs/invalid-thing", func(r *http.Request) {
+				r.Header.Set("Accept", "text/html")
+			})
+			assert.NotEqual(t, http.StatusOK, res.StatusCode)
+			assert.NotContains(t, res.Resp.Header.Get("Content-Type"), "text/html")
+		})
+	})
 }
--- a/test/dependencies/go.mod
+++ b/test/dependencies/go.mod
@ -7,7 +7,7 @@ replace github.com/ipfs/kubo => ../../
 require (
 	github.com/Kubuxu/gocovmerge v0.0.0-20161216165753-7ecaa51963cd
 	github.com/golangci/golangci-lint v1.54.1
-	github.com/ipfs/boxo v0.13.0
+	github.com/ipfs/boxo v0.13.1
 	github.com/ipfs/go-cid v0.4.1
 	github.com/ipfs/go-cidutil v0.1.0
 	github.com/ipfs/go-datastore v0.6.0
--- a/test/dependencies/go.sum
+++ b/test/dependencies/go.sum
@ -396,8 +396,8 @@ github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2
 github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
 github.com/ipfs/bbloom v0.0.4 h1:Gi+8EGJ2y5qiD5FbsbpX/TMNcJw8gSqr7eyjHa4Fhvs=
 github.com/ipfs/bbloom v0.0.4/go.mod h1:cS9YprKXpoZ9lT0n/Mw/a6/aFV6DTjTLYHeA+gyqMG0=
-github.com/ipfs/boxo v0.13.0 h1:uzCQekieYS4PysbYYdodNmKLuqOdLjlUziXVZ19oDeQ=
-github.com/ipfs/boxo v0.13.0/go.mod h1:btrtHy0lmO1ODMECbbEY1pxNtrLilvKSYLoGQt1yYCk=
+github.com/ipfs/boxo v0.13.1 h1:nQ5oQzcMZR3oL41REJDcTbrvDvuZh3J9ckc9+ILeRQI=
+github.com/ipfs/boxo v0.13.1/go.mod h1:btrtHy0lmO1ODMECbbEY1pxNtrLilvKSYLoGQt1yYCk=
 github.com/ipfs/go-bitfield v1.1.0 h1:fh7FIo8bSwaJEh6DdTWbCeZ1eqOaOkKFI74SCnsWbGA=
 github.com/ipfs/go-bitfield v1.1.0/go.mod h1:paqf1wjq/D2BBmzfTVFlJQ9IlFOZpg422HL0HqsGWHU=
 github.com/ipfs/go-block-format v0.1.2 h1:GAjkfhVx1f4YTODS6Esrj1wt2HhrtwTnhEr+DyPUaJo=