[Pulp-list] v2 Client Login/Logout

[Jay Dobies]

On 04/04/2012 09:44 PM, Nick Coghlan wrote:
> On 04/05/2012 03:47 AM, Jay Dobies wrote:
>> In fact, now that you mention it, the better approach would be to rename
>> the old client to pulp-v1-admin and start calling this pulp-admin
>> directly. I may try to slide that in soon.
>
> A related question - have there been many changes in the client
> implementation layout? I dig into a few of the existing CLI internals to
> get Pulp server access from the PulpDist web UI and the plugin test
> suite working over OAuth (and playing nice with Django's logging
> configuration), and I assume I'm eventually going to run into an upgrade
> that breaks my customisations (entirely my fault of course, since I
> *know* I'm messing around with undocumented internal details - some with
> underscore prefixed names, no less!).
>
> So I expect to have to rewrite parts of my client-side code [1] at some
> point, I'm just wondering if "at some point" actually means "when I
> upgrade from Pulp 0.267" :)

Ya, once you get into the mid 0.270s you'll see the changes. The idea is 
the client-lib package will be documented enough where I should be able 
to point you towards the docs to learn everything you need to know, but 
it's just not there yet. So here's a quick summary.

= Server Stub =
The actual piece you instantiate with the credentials/location of the 
server is largely unchanged. I think it's renamed, but the info passed 
to it is very similar.

One nice change is that the REST log filename is now specified to the 
constructor. If you pass that in, the REST for all calls will be logged 
to that file. It's been really helpful already to see exactly what's 
coming back from the server.

= Bindings =
The bindings themselves, when created, accept the server you've 
configured. Methods have moved, but now that I think about it you may 
not even be using these yet since the v1 client didn't have most of the 
APIs you'd want to be using.

= Responses & Exceptions =
This is the biggest change. The v1 client wrapped every server-side 
exception into a generic ServerRequestException and lost a good deal of 
data on what the error was.

Now there are client-side exceptions that, for the most part, correspond 
directly to the HTTP status codes that may come out of Pulp (e.g. 
BadRequestException, NotFoundException). Pulp now has a common REST 
exception format and a standard set of data for each status code, so 
we're able to unpack that information in the exception itself. See 
pulp.gc_client.api.exceptions (and expect that the gc_client part will 
be renamed when we start trashing v1 code and moving the v2 stuff over).

Also see pulp.gc_client.framework.exceptions. That's my client-side 
exception handler that rips out the relevant data from each exception 
type and builds up a consistent error message. It should help explain 
what I mean by the extra data dependent on exception type.

Each call into the server will return one of two response object classes:

* Response - Means the call was executed on the server and got back a 
200 or 201. It contains the actual code and the body of the response.

* AsyncResponse - Means the server returned a 202 (that's Accepted 
right? I feel like I'm confusing 201 and 202). It contains a standard 
block of information on the task as it's running on the server. That 
information, by its nature, take a bit to interpret, so that 
AsyncResponse class also provides a number of methods to easily 
interpret the state (e.g. is_running, is_waiting, is_postponed).

Many calls have the potential to return either response type. For 
instance, if I try to delete a repo, it'll probably return Response. But 
if that repo is currently busy, I'll get back an AsyncResponse. There 
are a number of places in the v2 client code where I do an instance 
check to determine what happened and react accordingly.

Feel free to ping me once you start looking at it. I'm just not on top 
of the docs for it yet and this e-mail wasn't a perfect substitute for 
that yet.



> Regards,
> Nick.
>
> [1]
> http://git.fedorahosted.org/git/?p=pulpdist.git;a=blob;f=src/pulpdist/core/pulpapi.py
>
>


-- 
Jay Dobies
Freenode: jdob @ #pulp
http://pulpproject.org | http://blog.pulpproject.org