[Freeipa-devel] Implementing --all as a global option

[Jason Gerard DeRose]

On Thu, 2010-02-04 at 15:55 +0100, Pavel Zuna wrote:
> Pavel Zuna wrote:
> > I've run into a little problem when implementing --all as a global 
> > option. The problem is that I can't see a way, to propagate it to the 
> > server side. Plugins could always retrieve all attributes and the client 
> > would choose what to display, but that would be very ineffective 
> > (especially when executing *-find commands).
> > 
> > Either we add a way to pass additional information over XML-RPC (command 
> > independent flags) or we go back to non-global --all options.
> > 
> > Thoughts?
> > 
> > Pavel
> > 
> 
> Hey Jason,
> we talked about this a bit on Tuesday meeting and you mentioned having some 
> plans about extending the information being transmitted over XML-RPC. I remember 
> something about "extras" and "cookies", but that's pretty much it. If you could 
> just summarize what you had in mind, I'll start figuring stuff out and 
> implementing it.
> 
> Pavel
> 

Sure.  XML-RPC arguments are supplied in a single params list (this is
the XML-RPC spec, not an IPA specific thing).  Right now our calling
signature is:

    [arg1, arg2, ..., argN, <options?>]

We make an educated guess as to whether the last argument is in fact an
options dict based on its type.  This works for now as the parameter
system doesn't yet support compound dict values (it only supports
compound list values, which you create using multivalue=True).  I'm sure
it's only a matter of time till we need compound dict values, so we
really need to change the XML-RPC signature before we release v2 and
become obligated to stay backward compatible.

I propose we change the signature to:

    [args, options, extra]

Where:

   `args` is a list of arguments for the command (can be empty)
   `options` is a dict of options for the command (can be empty)
   `extra` is a dict of extensible special variables (can be empty)

We really need the `extra` dict because a lot of XML-RPC libraries don't
make it especially easy (if even possible) to set HTTP headers (the
Python implementation included).  So my main use case for `extra` is to
pass things like cookies and the locale when they can't be supplied in
the HTTP headers.  Global options like --all are also a great use case
for `extra`, and I'm sure we'll have more down the road.  If something
like the locale is present in both the HTTP headers and in `extra`, the
value in `extra` should take precedence.

We should allow `extra`, `options`, and `args` to be missing in the call
so that all of these would be valid calls:

    []  # Implies [[], {}, {}]

    [['foo']]  # Implies [['foo'], {}, {}]

    [[], {'foo': 'bar'}]  # Implies [[], {'foo': 'bar'}, {}]

    [[], {}, {'foo': 'bar'}]

Make sense?  Does anyone disagree with this approach, have suggestions?

The JSON-RPC call signature is already [args, options]... and I'll
change this to [args, options, extra] shorty after the alpha release.