[packagekit] RFC: Use 5 package states rather than 2 (big break in API)

[Richard Hughes]

At the moment, there are two big problems in the Resolve API:

* Resolve has lots of black logic required to get the "correct" answers;
resolve is used in lots of different ways
* A package has only two states, available or installed (or both, under
some circumstances)

The current rules go something like this:

1. if a package is installed output "installed"
2. if a package is available but not installed output "available"
3. if we specify filters, the first two rules have to be broken. Ish.

Needless to say, this isn't very flexible, and won't let us do things
like:

* Reinstall packages
* Revert to a specific version of a package
* Specify in the client UI if an available package is an upgrade
(here-on known as update), downgrade (aka. revert) or re-install (aka.
replay)

Recently I've been working with onestep on IRC, as the current API is
just not suitable for him to use.

Any API break has to be backwards compatible with client code (not all
backends have the resources to convert straight away) and also need to
heed these points:

* When we search with "--filter=installed" we can't open the repos, as
on some backends opening the repos is slow (yum) but reading the system
database is fast (rpm). So we can't return a type of
"installed_but_upgradable"
* Unlike now, resolve should have exactly the same semantics as search,
except resolve is an exact package name match rather than a search term.
This was the way it was originally designed.

So, our proposal:

************************************************************
A package_id can be in one of 5 states (one local, 4 remote):

installed:  Installed on the local machine
available:  Not installed, can be installed
replay:     Installed, can re-install from a repo with the same version
update:     Lesser version installed than available, can update
revert:     Bigger version installed than available, can undo an update

Affect of filters:

 installed => installed
~installed => (available, replay, update, revert)
 newest    => (available, installed, update)
              displays newest computed from installed _and_ available
              unless installed or ~installed filter is set
~newest    => (available, installed, replay, revert)
              less commonly used

************************************************************
local: aaa-001
repo:  aaa-001
repo:  aaa-002

resolve aaa
installed       aaa-001         A package for testing
replay          aaa-001         A package for testing
update          aaa-002         A package for testing

resolve aaa --filter=installed
installed       aaa-001         A package for testing

resolve aaa --filter=~installed
replay          aaa-001         A package for testing
update          aaa-002         A package for testing

resolve aaa --filter=newest
installed       aaa-001         A package for testing
update          aaa-002         A package for testing

resolve aaa --filter=~newest
installed       aaa-001         A package for testing
replay          aaa-001         A package for testing

resolve aaa --filter=~installed;newest
update          aaa-002         A package for testing

************************************************************
local: aaa-002
repo:  aaa-001
repo:  aaa-002

resolve aaa
installed       aaa-002         A package for testing
revert          aaa-001         A package for testing
replay          aaa-002         A package for testing

resolve aaa --filter=installed
installed       aaa-002         A package for testing

resolve aaa --filter=~installed
revert          aaa-001         A package for testing
replay          aaa-002         A package for testing

************************************************************
local: aaa-002

resolve aaa
installed       aaa-002         A package for testing

resolve aaa --filter=installed
installed       aaa-002         A package for testing

resolve aaa --filter=~installed

************************************************************
repo:  aaa-002

resolve aaa
available       aaa-002         A package for testing

resolve aaa --filter=installed
-
resolve aaa --filter=~installed
available       aaa-002         A package for testing

resolve aaa --filter=~installed;newest
available       aaa-002         A package for testing

************************************************************
local  kernel-001
local  kernel-002
local  kernel-003
repo:  kernel-003
repo:  kernel-004

resolve kernel
installed       kernel-001      Linux kernel
installed       kernel-002      Linux kernel
installed       kernel-003      Linux kernel
replay          kernel-003      Linux kernel
update          kernel-004      Linux kernel

resolve kernel --filter=installed
installed       kernel-001      Linux kernel
installed       kernel-002      Linux kernel
installed       kernel-003      Linux kernel

resolve kernel --filter=installed;newest
installed       kernel-003      Linux kernel

resolve kernel --filter=~installed
replay          kernel-003      Linux kernel
update          kernel-004      Linux kernel

resolve kernel --filter=~installed;newest
update          kernel-004      Linux kernel

************************************************************

In this way, legacy backends can just emit available and installed like
before. There should be no effects other than the client tools sometimes
not displaying the correct button labels, and the loss of little used
functionality like replay and revert. Client tools can filter on things
like replay (if it's a simple tool) or the backend could just not send
action that are not supported, for instance with rpm and revert.

If this RFC is agreed, then we'll obviously branch for 0_4_X before we
start work. What do you think? Comments welcome. Thanks.

Richard.