Subject: Re: [PATCH v4 27/35] transport-helper: introduce stateless-connect

From: Brandon Williams <[email-masked]>
Date: Wed, 14 Mar 2018 10:36:52 -0700

On 03/13, Jonathan Tan wrote:
> On Wed, 28 Feb 2018 15:22:44 -0800
> Brandon Williams <[email-masked]> wrote:
> 
> > +'stateless-connect'::
> > +	Experimental; for internal use only.
> > +	Can attempt to connect to a remote server for communication
> > +	using git's wire-protocol version 2.  This establishes a
> > +	stateless, half-duplex connection.
> > ++
> > +Supported commands: 'stateless-connect'.
> > +
> >  'push'::
> >  	Can discover remote refs and push local commits and the
> >  	history leading up to them to new or existing remote refs.
> > @@ -136,6 +144,14 @@ Capabilities for Fetching
> >  +
> >  Supported commands: 'connect'.
> >  
> > +'stateless-connect'::
> > +	Experimental; for internal use only.
> > +	Can attempt to connect to a remote server for communication
> > +	using git's wire-protocol version 2.  This establishes a
> > +	stateless, half-duplex connection.
> > ++
> > +Supported commands: 'stateless-connect'.
> 
> I don't think we should use the term "half-duplex" - from a search, it
> means that both parties can use the wire but not simultaneously, which
> is not strictly true. Might be better to just say "see the documentation
> for the stateless-connect command for more information".
> 
> > +'stateless-connect' <service>::
> > +	Experimental; for internal use only.
> > +	Connects to the given remote service for communication using
> > +	git's wire-protocol version 2.  This establishes a stateless,
> > +	half-duplex connection.  Valid replies to this command are empty
> > +	line (connection established), 'fallback' (no smart transport
> > +	support, fall back to dumb transports) and just exiting with
> > +	error message printed (can't connect, don't bother trying to
> > +	fall back).  After line feed terminating the positive (empty)
> > +	response, the output of the service starts.  Messages (both
> > +	request and response) must be terminated with a single flush
> > +	packet, allowing the remote helper to properly act as a proxy.
> > +	After the connection ends, the remote helper exits.
> > ++
> > +Supported if the helper has the "stateless-connect" capability.
> 
> I'm not sure of the relevance of "allowing the remote helper to properly
> act as a proxy" - this scheme does make it easier to implement proxies,
> not for any party to start acting as one instead. I would write that
> part as:
> 
>     Messages (both request and response) must consist of zero or more
>     PKT-LINEs, terminating in a flush packet. The client must not expect
>     the server to store any state in between request-response pairs.
> 
> (This covers the so-called "half-duplex" part and the "stateless" part.)

Thanks for helping wordsmith this, I'll update the docs based on these
suggestions.

-- 
Brandon Williams