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
-----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.
server@lists.fedoraproject.org