From 8efec25ec0d7c6a395608081871537f37e9d45b8 Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Thu, 13 Jul 2023 17:01:08 +0200
Subject: [PATCH] docs: ipip-412 changelog and better error messages

---
 CHANGELOG.md              | 28 ++++++++++++++++++++--------
 gateway/blocks_backend.go |  2 +-
 gateway/handler_car.go    |  8 ++++----
 3 files changed, 25 insertions(+), 13 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64ec2f354f..77f0b97a88 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,17 +17,29 @@ The following emojis are used to highlight certain changes:
 ### Added
 
 * ✨ The gateway now supports the optional `order` and `dups` CAR parameters
-  from [IPIP-412](https://github.com/ipfs/specs/pull/412). `BlocksBackend` only
-  DFS ordering. If the request explicitly requests an ordering other than `dfs`
-  and `unk`, the request will return an error.
+  from [IPIP-412](https://github.com/ipfs/specs/pull/412).
+  * The `BlocksBackend` only implements `order=dfs` (Depth-First Search)
+    ordering, which was already the default behavior.
+  * If a request specifies no `dups`, response with `dups=n` is returned, which
+    was already the default behavior.
+  * If a request explicitly specifies a CAR `order` other than `dfs`, it will
+    result in an error.
+  * The only change to the default behavior on CAR responses is that we follow
+    IPIP-412 and make `order=dfs;dups=n` explicit in the returned
+    `Content-Type` HTTP header.
 
 ### Changed
 
-* 🛠 The `ipns` package has been refactored. You should no longer use the direct Protobuf
-  version of the IPNS Record. Instead, we have a shiny new `ipns.Record` type that wraps
-  all the required functionality to work the best as possible with IPNS v2 Records. Please
-  check the [documentation](https://pkg.go.dev/github.com/ipfs/boxo/ipns) for more information,
-  and follow [ipfs/specs#376](https://github.com/ipfs/specs/issues/376) for related IPIP.
+* 🛠 The `ipns` package has been refactored.
+  * You should no longer use the direct Protobuf version of the IPNS Record.
+    Instead, we have a shiny new `ipns.Record` type that wraps all the required
+    functionality to work the best as possible with IPNS v2 Records. Please
+    check the [documentation](https://pkg.go.dev/github.com/ipfs/boxo/ipns) for
+    more information, and follow
+    [ipfs/specs#376](https://github.com/ipfs/specs/issues/376) for related
+    IPIP.
+  * There is no change to IPNS Records produced by `boxo/ipns`, it still
+    produces both V1 and V2 signatures by default, it is still backward-compatible.
 
 ### Removed
 
diff --git a/gateway/blocks_backend.go b/gateway/blocks_backend.go
index f7e7606095..61aaa193fb 100644
--- a/gateway/blocks_backend.go
+++ b/gateway/blocks_backend.go
@@ -242,7 +242,7 @@ func (bb *BlocksBackend) GetCAR(ctx context.Context, p ImmutablePath, params *Ca
 	case DagOrderDFS:
 		// Do nothing
 	default:
-		return ContentPathMetadata{}, nil, fmt.Errorf("unsupported order: %s", params.Order)
+		return ContentPathMetadata{}, nil, fmt.Errorf("unsupported application/vnd.ipld.car block order parameter: %q", params.Order)
 	}
 
 	// Similarly, if params.Duplicates is not set, let's set it to false.
diff --git a/gateway/handler_car.go b/gateway/handler_car.go
index 3e38cb09bf..d227055c36 100644
--- a/gateway/handler_car.go
+++ b/gateway/handler_car.go
@@ -122,7 +122,7 @@ func getCarParams(r *http.Request, formatParams map[string]string) (*CarParams,
 	if hasRange {
 		rng, err := NewDagByteRange(rangeStr)
 		if err != nil {
-			err = fmt.Errorf("invalid entity-bytes: %w", err)
+			err = fmt.Errorf("invalid application/vnd.ipld.car entity-bytes URL parameter: %w", err)
 			return nil, err
 		}
 		params.Range = &rng
@@ -133,7 +133,7 @@ func getCarParams(r *http.Request, formatParams map[string]string) (*CarParams,
 		case DagScopeEntity, DagScopeAll, DagScopeBlock:
 			params.Scope = s
 		default:
-			err := fmt.Errorf("unsupported dag-scope %s", scopeStr)
+			err := fmt.Errorf("unsupported application/vnd.ipld.car dag-scope URL parameter: %q", scopeStr)
 			return nil, err
 		}
 	} else {
@@ -146,7 +146,7 @@ func getCarParams(r *http.Request, formatParams map[string]string) (*CarParams,
 	case "":
 		params.Order = DagOrderUnknown
 	default:
-		return nil, fmt.Errorf("unsupported order %s", order)
+		return nil, fmt.Errorf("unsupported application/vnd.ipld.car content type order parameter: %q", order)
 	}
 
 	switch dups := formatParams["dups"]; dups {
@@ -159,7 +159,7 @@ func getCarParams(r *http.Request, formatParams map[string]string) (*CarParams,
 	case "":
 		// Acceptable, we do not set anything.
 	default:
-		return nil, fmt.Errorf("unsupported dups %s", dups)
+		return nil, fmt.Errorf("unsupported application/vnd.ipld.car content type  dups parameter:  %q", dups)
 	}
 
 	return &params, nil