[PATCH] gitprotocol-http: document invalid 'want' error handling

[PATCH] gitprotocol-http: document invalid 'want' error handling

[QueenJcloud]

Add documentation to describe how the server responds when a client sends an
invalid 'want' line during the HTTP protocol exchange. This helps clarify the
behavior of Git when handling malformed or unknown object requests, and
ensures developers understand how such errors are reported.

Signed-off-by: Queen Ediri Jessa <qjessa662@gmail.com>
---
 Documentation/gitprotocol-http.adoc | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

diff --git a/Documentation/gitprotocol-http.adoc b/Documentation/gitprotocol-http.adoc
index d024010414..8818e9dc03 100644
--- a/Documentation/gitprotocol-http.adoc
+++ b/Documentation/gitprotocol-http.adoc
@@ -443,7 +443,17 @@ If no "want" objects are received, send an error:
 TODO: Define error if no "want" lines are requested.
 
 If any "want" object is not reachable, send an error:
-TODO: Define error if an invalid "want" is requested.
+When the client sends an invalid `want` line, the server responds with an
+appropriate error message indicating the invalid object request. This ensures
+the client can detect and handle protocol violations gracefully.
+
+For example, a malformed or unknown object hash in a `want` command will result
+in a response similar to:
+
+    error invalid 'want' <object-id>
+
+This helps maintain clear communication between client and server during
+fetch operations.
 
 Create an empty list, `s_common`.
 
-- 
2.51.0.573.gb660e2dcb9

Re: [PATCH] gitprotocol-http: document invalid 'want' error handling

[Junio C Hamano]

QueenJcloud <qjessa662@gmail.com> writes:

In the header part of this e-mail, we see this name/address

> From: QueenJcloud <qjessa662@gmail.com>

which I know from the past exchange is different from what you want
to be known as to this community (you have your preferred identity
on the Signed-off-by: line we see below).  In such a case, you can
do one of two things.

 * Fix your mail client program so that it places your preferred
   identity on the "From:" header; or

 * Start the body of your message with an extra "in-body header",
   i.e. "From: Queen Ediri Jessa <qjessa662@gmail.com>", and a blank
   line to separate the in-body header from the body of the message.

The former may be preferable, as you'd need to do so only once.

> Add documentation to describe how the server responds when a client sends an
> invalid 'want' line during the HTTP protocol exchange. This helps clarify the
> behavior of Git when handling malformed or unknown object requests, and
> ensures developers understand how such errors are reported.

Is it describing what happens to be the behaviour of one
implementation (namely, ours), or do all server implementations give
identical error message?  Back when the TODO: comment was written
and back when there weren't other reimplementations of Git, by
definition the error message our implementation give would have been
the only official one.  But now, it is way too late to declare "here
is what our implementation gives out, so everybody else must do the
same or they are in error".  We'd need to clarify what the intention
of this update is in this part of the proposed log message,
something like "HTTP server implementation of git-core and jGit give
different messages but since their messages share this and that
characteristics, which is something any reasonable reimplementations
of Git would sharee, specify that as the requirement here" (I am not
claiming that it was what you did to come up with this patch and
what you want the text of the patch to be taken as; I am just giving
a rough illustration of the level of detail expected in the proposed
log message to explain what backs the new text in the documentation
and how seriously the server implementors need to take it).

>  If any "want" object is not reachable, send an error:
> +When the client sends an invalid `want` line, the server responds with an
> +appropriate error message indicating the invalid object request. This ensures
> +the client can detect and handle protocol violations gracefully.
> +
> +For example, a malformed or unknown object hash in a `want` command will result
> +in a response similar to:
> +
> +    error invalid 'want' <object-id>
> +
> +This helps maintain clear communication between client and server during
> +fetch operations.

I am not sure if the additional information given here is worth this
many number of lines.  Wouldn't something like this

	If any "want" object is not reachable, send an error message
	that includes the offending object name to help the client
	diagnose which "want" command was the bad one.

tell the same thing more concisely and clearly?

Thanks.