Re: [cpp-netlib-devel] Comments about the HTTP client interface

[Dean M. B. <mik...@gm...>]

Hi Kim,

On Thu, Aug 28, 2008 at 2:47 PM, Kim Gräsman <kim...@gm...> wrote:
>
> On Thu, Aug 28, 2008 at 03:47, Dean Michael Berris
> <mik...@gm...> wrote:
>>
>> For #2:
>> - It puts the method crafting a 'run-time' action, which introduces
>> if's and control-flow branches that I would like to be able to
>> eliminate at compile time otherwise
>> - Type safety (?) is broken because now the users will be able to
>> perform 'unsupported' or 'ill-formed' HTTP requests
>
> I can't think of one off-hand, but I think there may be cases where it
> makes sense to let the calling code vary the verb dynamically.
> Essentially, something like:
>
>  client.request("POST", headers, body);
>
> So, #2 may not be all bad--after all it's all strings in the end :)
>

Unfortunately, this is not acceptable for me because:

1. The request object is nowhere to be found (http::request object),
which should encapsulate all this information (headers, body) already
which is of very little consequence to the client.
2. The creation of the request object is by design decoupled from the
HTTP client because operations on the request object (like
adding/inspecting headers, adding/inspecting the body, other message
processing routines (conversion, transformation, serialization, etc.)
) are of no consequence (on the contrary, are actually used by) the
client.
3. This means inside client::request(...) I'll have to check whether I
will ignore/use the body depending on the method string provided.
Contrast that to a fixed interface which actually at compile time only
puts the code that's needed to perform the request without having to
do checks of what to do at runtime.

> I like the strongly named methods as they are now, but a generic
> request may be useful as well, otherwise you might _introduce_
> control-flow branches for calling the right method in cases where the
> verb is not fixed.
>

It depends what you mean by 'useful'.

One of the reasons why the library is intended to be header-only is to
minimize a lot of the run-time decision making from even happening by
making decisions at compile-time. For instance if you look at the
implementation of the http::client, there is a skeleton implementation
where the determination of whether to read the body of the response is
made/optimized at compile time (comparing HEAD and GET requests).

The static mapping between the behavior of client::get and HTTP GET
requests is intentional because primarily:

1. I don't see a point in making it a run-time check when it can be
made clear at compile-time.
2. The semantics of usage are unclear when using 'dynamic' or runtime
values to do the decision making that can otherwise be done at compile
time in a clearer manner.

So the idea really here is, the if's and control flow that is
application specific should remain application specific. For instance,
you can craft the request object in a generic manner, and do an 'if'
to find out whether you'll be using client.put(...) or
client.post(...) given the same http::request instance. I find for
example this if to be better put in the user code to convey clear
semantics, rather than be in the library where I should concentrate on
the efficiency of the implementation on a per-method level. ;-)

> That said, I can't think of a good case at the moment... As such,
> maybe better to leave it until need arises, but I don't think it can
> be entirely discounted.
>

I personally find no merit in allowing for making the method a runtime
string (and having a "generic" client::perform(...) ) unless for
instance you want to layer on top of an HTTP client a WebDAV
implementation. In this sense, I would rather have the WebDAV client
implementation inherit from the HTTP client and re-use internal
methods rather than just merely use a generic "unsafe" interface
provided by the HTTP client.

If helping the developer avoid shooting themselves in the foot matters
(which I really think does, a lot) then keeping the static mapping and
semantics intact would be a good premium. I'd think it's more a
feature than a deficiency that the HTTP client allows for an
expressive interface to allow users to "say what they mean" instead of
leaving a wide open door to allow users to easily get things wrong.
One of the goals is to make it easier to use the library, and part of
that is to make 'getting it wrong' harder than getting it right. :)

> Well, 2c worth,

2c is a worth a lot from where I am. :-P

-- 
Dean Michael C. Berris
Software Engineer, Friendster, Inc.