Fedora Server Role D-BUS API Design Discussion

[Jan Safranek]

I'm injecting the old "Fedora Server Role D-BUS API Design Discussion"
thread as I was not subscribed at that time... I looked at the API and I
have few remarks:

First, don't use under_scores, DBus prefers CamelCase.

> /org/fedoraproject/server/ServerRoleManager:
> * properties:
>   * all_roles:     list of object references to Roles that can be
>                    installed and deployed
>   * staging_roles: list of object references to Roles that have been
>                    pre-loaded but not yet configured
>   * active_roles:  list of object references to deployed Roles
>   * version:       API version
> * methods:

It would be nice if there was e.g. /org/fedoraproject/server/ServerRole
object with org.freedesktop.DBus.ObjectManager interface, which would
list all objects provided by the service. That's how DBus works usually.
It may make 'all_roles', 'staging_roles' and 'active_roles' properties
of ServerRoleManager irrelevant, as an application can easily list all
object + filter out those with appropriate properties.

> /org/fedoraproject/server/role/$ROLE:
> * properties:
>   * version:          API version
>   * loaded:           Bool: whether the packages are installed
>   * deployed:         Bool: whether the Role has been deployed
> * methods:
>   * PreloadRole:      Install all necessary software packages for
>                       default operation
>   * GetFirewallPorts: list of port/protocol pairs that the Role needs
>                       open in the firewall
>   * PrepBackup:       method to invoke any necessary pre-backup steps
>                       (such as running a database dump to a file)
>   * GetBackupFiles:   list of filesystem path objects that identifies
>                       all data that should be copied by backup software
>
> # Individual Roles should have unique implementations of installation
> # and deployment
> 
> e.g. /org/fedoraproject/server/role/DomainController
> * methods:
>   * DeployPrimaryDomainController: Set up the first domain controller in
>                                    the domain.
>   * DeployReplicaDomainController: Add a new replica domain controller
>                                    to the domain
>   * AddCertificateAuthority:       Add a certificate authority to this
>                                    domain controller
>   * EnableDisableDNS:              Enable or disable the DNS server on
>                                    this server

I am not sure if DBus supports inheritance. I have seen only single
object implementing multiple interfaces, i.e.
/org/fedoraproject/Server/Role/DomainController would implement both,
org.fedoraproject.Server.Role.Generic [or so] and
org.fedoraproject.Server.Role.DomainController, each with distinct
properties and methods.

And most importantly, there must be some sort of job management. I guess
installing role packages and deploying a role are long running
operations in general. In this case, the DeployPrimaryDomainController()
method should return a reference to a new object with Job interface, which:
- can be watched for progress [i.e. Cockpit draws a nice progress bar]
- reports any error messages [Cockpit shows an error alert]
- with possibility to cancel the job if such functionality is needed and
feasible.
There may be more than one running jobs, started by [in theory]
different Cockpit users, so all needs to be robust enough e.g. to queue
jobs and execute them serially.

As consequence, simple boolean for Role.Generic.loaded and .deployed may
not be enough, some 'in progress' would be nice.

I am afraid it's not _that_ simple DBus service as initially planned.
It's not particularly difficult either, it just needs a good design. And
the API should be reviewed by someone who really understands DBus and
knows its design patterns, so it fits well there. I am certainly not an
expert here, I just have played a bit with few services like UDisks and
storaged and I can spot only the most obvious issues.

Jan