feat(gateway): add AllowCodecConversion config option

Add AllowCodecConversion to gateway.Config to control codec conversion
behavior per IPIP-0524. When false (default), the gateway returns
406 Not Acceptable if the requested format doesn't match the block's
codec. When true, conversions between codecs are performed for backward
compatibility.

Codec conversion tests moved here from gateway-conformance since
conversions are now an optional implementation feature, not a spec
requirement. Gateway-conformance now tests for 406 responses.

Ref: ipfs/specs#524
Ref: ipfs/gateway-conformance#254

Author: lidel

gateway/gateway.go

@@ -52,6 +52,19 @@ type Config struct {
 	// [Trustless Gateway]: https://specs.ipfs.tech/http-gateways/trustless-gateway/
 	DeserializedResponses bool
 
+	// AllowCodecConversion enables automatic conversion between codecs when
+	// the requested format differs from the block's native codec. For example,
+	// converting dag-pb (UnixFS) to dag-json.
+	//
+	// When false (default), the gateway returns 406 Not Acceptable if the
+	// requested format doesn't match the block's codec. This follows the
+	// behavior specified in IPIP-0524.
+	//
+	// When true, the gateway attempts to convert between legacy IPLD formats.
+	// This is provided for backwards compatibility but is not required by
+	// the gateway specification.
+	AllowCodecConversion bool
+
 	// NoDNSLink configures the gateway to _not_ perform DNS TXT record lookups in
 	// response to requests with values in `Host` HTTP header. This flag can be
 	// overridden per FQDN in PublicGateways. To be used with WithHostname.

gateway/gateway_test.go

@@ -521,6 +521,7 @@ func TestHeaders(t *testing.T) {
 				},
 			},
 			DeserializedResponses: true,
+			AllowCodecConversion:  true, // Test tests various format conversions
 		})
 
 		runTest := func(name, path, accept, host, expectedContentLocationHdr string) {
@@ -1073,7 +1074,8 @@ func TestDeserializedResponses(t *testing.T) {
 		backend, root := newMockBackend(t, "fixtures.car")
 
 		ts := newTestServerWithConfig(t, backend, Config{
-			NoDNSLink: false,
+			NoDNSLink:            false,
+			AllowCodecConversion: true, // Test expects codec conversions to work
 			PublicGateways: map[string]*PublicGateway{
 				"trustless.com": {
 					Paths: []string{"/ipfs", "/ipns"},
@@ -1152,7 +1154,8 @@ func TestDeserializedResponses(t *testing.T) {
 		backend.namesys["/ipns/trusted.com"] = newMockNamesysItem(path.FromCid(root), 0)
 
 		ts := newTestServerWithConfig(t, backend, Config{
-			NoDNSLink: false,
+			NoDNSLink:            false,
+			AllowCodecConversion: true, // Test expects codec conversions to work
 			PublicGateways: map[string]*PublicGateway{
 				"trustless.com": {
 					Paths: []string{"/ipfs", "/ipns"},
@@ -1186,6 +1189,58 @@ func TestDeserializedResponses(t *testing.T) {
 	})
 }
 
+func TestAllowCodecConversion(t *testing.T) {
+	t.Parallel()
+
+	// Use dag-cbor fixture
+	backend, dagCborRoot := newMockBackend(t, "path_gateway_dag/dag-cbor-traversal.car")
+
+	t.Run("AllowCodecConversion=false returns 406 for codec mismatch", func(t *testing.T) {
+		t.Parallel()
+
+		ts := newTestServerWithConfig(t, backend, Config{
+			DeserializedResponses: true,
+			AllowCodecConversion:  false, // IPIP-0524 behavior
+		})
+
+		// Request dag-json for a dag-cbor block - should return 406
+		req := mustNewRequest(t, http.MethodGet, ts.URL+"/ipfs/"+dagCborRoot.String()+"?format=dag-json", nil)
+		res := mustDoWithoutRedirect(t, req)
+		defer res.Body.Close()
+		assert.Equal(t, http.StatusNotAcceptable, res.StatusCode)
+	})
+
+	t.Run("AllowCodecConversion=false allows matching codec", func(t *testing.T) {
+		t.Parallel()
+
+		ts := newTestServerWithConfig(t, backend, Config{
+			DeserializedResponses: true,
+			AllowCodecConversion:  false, // IPIP-0524 behavior
+		})
+
+		// Request dag-cbor for a dag-cbor block - should return 200
+		req := mustNewRequest(t, http.MethodGet, ts.URL+"/ipfs/"+dagCborRoot.String()+"?format=dag-cbor", nil)
+		res := mustDoWithoutRedirect(t, req)
+		defer res.Body.Close()
+		assert.Equal(t, http.StatusOK, res.StatusCode)
+	})
+
+	t.Run("AllowCodecConversion=true allows codec conversion", func(t *testing.T) {
+		t.Parallel()
+
+		ts := newTestServerWithConfig(t, backend, Config{
+			DeserializedResponses: true,
+			AllowCodecConversion:  true, // Legacy behavior
+		})
+
+		// Request dag-json for a dag-cbor block - should return 200 with conversion
+		req := mustNewRequest(t, http.MethodGet, ts.URL+"/ipfs/"+dagCborRoot.String()+"?format=dag-json", nil)
+		res := mustDoWithoutRedirect(t, req)
+		defer res.Body.Close()
+		assert.Equal(t, http.StatusOK, res.StatusCode)
+	})
+}
+
 type errorMockBackend struct {
 	err error
 }

gateway/handler_codec.go

@@ -148,7 +148,20 @@ func (i *handler) renderCodec(ctx context.Context, w http.ResponseWriter, r *htt
 		return false
 	}
 
-	// This handles DAG-* conversions and validations.
+	// IPIP-0524: Check if codec conversion is allowed
+	if !i.config.AllowCodecConversion && toCodec != cidCodec {
+		// Conversion not allowed and codecs don't match - return 406
+		err := fmt.Errorf("format %q requested but block has codec %q: codec conversion is not supported", rq.responseFormat, cidCodec.String())
+		i.webError(w, r, err, http.StatusNotAcceptable)
+		return false
+	}
+
+	// If codecs match, serve raw (no conversion needed)
+	if toCodec == cidCodec {
+		return i.serveCodecRaw(ctx, w, r, blockSize, blockData, rq.contentPath, modtime, rq.begin)
+	}
+
+	// AllowCodecConversion is true - perform DAG-* conversion
 	return i.serveCodecConverted(ctx, w, r, blockCid, blockData, rq.contentPath, toCodec, modtime, rq.begin)
 }
 

gateway/testdata/path_gateway_dag/dag-cbor-traversal.car

@@ -234,6 +234,7 @@ func newTestServerAndNode(t *testing.T, fixturesFile string) (*httptest.Server,
 func newTestServer(t *testing.T, backend IPFSBackend) *httptest.Server {
 	return newTestServerWithConfig(t, backend, Config{
 		DeserializedResponses: true,
+		AllowCodecConversion:  true, // Enable for backwards compatibility in tests
 		MetricsRegistry:       prometheus.NewRegistry(),
 	})
 }