[Authentication] Async API vs. Immediate

[Stef Walter]

So at this point, it looks like we need to decide something pretty
fundamental about our API. We need to decide whether we're going to have
operations that don't complete immediately, or whether we try to design
the API without that. This has primarily to do with prompting.

There are two approaches, each has drawbacks. The term 'operation' below
is used to describe an action requested by the client which changes
state in the service and can: a) fail b) be canceled.


LONG RUNNING OPERATIONS:

This is the model that gnome-keyring currently uses. I'm not a big fan
of this approach, but perhaps its more realistic.

Approach:

 * Operations can arbitrarily take a long time depending on the
   operation, and the current state.
 * Prompts which happen during the course of an operation cause
   that operation to be delayed until the prompt completes.
 * Either the DBus method itself takes a long time (simple), or we
   do some kind method calls with completion signals (very
   problem prone for non-simple operations).

Benefits:

 * Easy to implement for client applications.

Compromises:

 * A client application cannot predict whether a certain invocation of
   an operation will happen instantly or not.
 * Harder to implement for the Service.
 * Blocking calls are hard to get right in a DBus world where we're
   thwarted in one way or another depending on our design. [1]

One design based on this approach is the patch that I recently posted [2].


NO LONG RUNNING OPERATIONS:

I liked this idea in theory, but now we're running into some problems
with it.

Approach:

 * All operations complete or fail immediately.
 * Authentication is a special case, and causes prompts. Because
   prompting isn't really an operation, it easier to design an async
   callback.

Benefits:

 * Unlock requests are queued in a list, and signaled when they
   complete allowing an application to queue a bunch of unlocks,
   and only unlock as many as it needs.
 * Operation execution is very deterministic, and easy for client
   applications to know what to expect.

Compromises:

 * The type of operations that can be implemented are limited.
 * CreateCollection and ChangeAuthentication are second class citizens.

This approach is similar to the design we have so far.

The only outliers are CreateCollection and ChangeAuthentication. These
two might be implemented on an additional interface, as simple one way
calls, without notification of completion. As such they would be useful
to password managers to perform these actions on behalf of a user, but
not as useful to general client applications which wouldn't know when
these calls completed.



The descriptions are highly generalized, and either approach would need
to be fine tuned. But what we need to decide fundamentally which
approach to take in our design.

Cheers,

Stef


[1] http://marc.info/?l=freedesktop-dbus&m=121675537300488&w=2

[2] http://article.gmane.org/gmane.comp.freedesktop.authentication/20