Fedora Server Role D-BUS API Design Discussion

Mon Mar 24 21:20:30 UTC 2014

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 03/24/2014 12:47 PM, Jan Safranek wrote:
> 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.
> 

Noted. I hate CamelCase, but I'll bow to the convention.

>> /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.
> 

Good idea. As noted, I'm not tremendously familiar with D-BUS
interfaces and I'm learning as I go. That does sound like a useful way
to present the objects.

>> /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.
> 

In this situation, I was thinking of inheritance more from a
conceptual rather than implementation view. I meant that a consumer
should be able to assume that certain standard methods (with known
arguments) exist.

On the implementation side, I was using inheritance in my
quick-n-dirty dbus-python service to accomplish that.

> 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]

Very useful

> - with possibility to cancel the job if such functionality is
> needed and feasible.

This may be harder to accomplish, unless we build in snapshotting
capabilities. A lot of deployment-type activities would be difficult
to abort and restore to the original state. But I suppose if the role
supports it, certainly good to have.

> 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.
> 

Good point.

> 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.

I fully admit to not being that person, hence why this is a public
discussion :)

Thank you very much for your feedback. It's very helpful.