-
Notifications
You must be signed in to change notification settings - Fork 10
Gloves Use Cases
Examples of tasks for Glove (the high level) library. We are trying to gather the tasks so we can define the API.
General rules:
- Return value of Write functions is hash of type ("message" and "error_id" are not needed when the value of "success" is true):
{ "success" => boolean, "message" => string, "error_id" => string }
-
Return value of read functions, is always hash
-
Alternative proposal is to raise an exception in case of error, both while reading and writing. In such case, standard return value of write would not be defined, but would be used only if needed for special cases (like, returning data map of user just added or so).
-
We agreed to use 3 types of Write functions: Add, Modify, Delete instead of single Write.
-
For Write-kind of functions, use 2 hash arguments. Firsts one contains identification about the object that should be modified (user, bootloader section, whole kerberos configuration). Second hash contains the actual data to be used with given action (user name, kerberos server address etc.).
-
For Read, one argument should be enough. It specifies more precisely, what part of data do we want to get. In the default situation, argument map is empty and Read returns all available data specific for the library (like, list of all users or whole kerberos configuration).
-
There are certain predefined keys that could be used in argument hashes:
-
id - find an object identified with id. Value of id varies, depending on what minimum identification is needed for given object: for users it is just a string (username), for dhcp section the id might be more complicated structure
-
filter - find all objects satisfying given condition (like all users with given UID)
-
only - restrict the output to the given parts
-
kind - restrict the search so certain type of objects (like only search among bootloader sections instead of in global obtions)
In general, first map could contain "kind" => "user" argument. But since all actions are done for user(s), this should be not necessary.
read ({ "id" => "root" })
Returns hash with user info, like
{ "username" => "root", "uid" => 0 }
read ({ "filter" => { "type" => "ldap" } })
Returns hash with list inside:
{ "result" => [ { "username" => "ldap1", "uid" => 1111}, { "username" => "ldap2", "uid" => 2222 } ] }
read ({ "only" => "username"})
Should return list of string, however maybe inside some hash to keep the return value type the same:
{ "result" => [ "at", "avahi", "bin" ... ] }
Add new user with name "hh" and password "password", without specifying UID. Do NOT create home directory.
add ( { }, { "username" => "hh", "password" => "password", "create_home" => false })
modify ({ "id" => "hh" }, { "username" => "jj" })
delete ({ "id" => "jj" }, { "delete_home" => true })
read ($[])
Returns one level hash with all related data, like
{ "minimum_uid"=>"0", "default_domain"=>"suse.cz", "default_realm"=>"SUSE.CZ", "kdc"=>"kdc.suse.cz"}
Alternatively, returns map structured the same way as Export/Import functions of yast2-kerberos-client (using "kerberos_client" and "pam_login" submaps, distingushing krb5.conf based data from PAM related ones):
{ "kerberos_client"=> { "default_realm"=>"SUSE.CZ" }, "pam_login"=>{ "sssd"=>false, "use_kerberos"=>false} }
It should be able to pass only changed data, not the whole map we got from read function.
modify ({ "kind" => "all" }, { "kerberos_client" => { "default_realm" => "SUSE.DE" }})
We do not have to pass anything in the first hash argument hash, we're always doing the same work. JR: for consistency I recommend to use as action modify and without parameter have just a shortcut ( because in future we maybe want to extend it, so empty action is then modify ).
I use there slightly different proposal with unified read actions modified by kind. So for modify there is always action modify and just depends on kind what is changed.
read ({ "kind" => "all" })
Returns hash with all bootloader settings, like
{ 'global' => {...}, 'sections => [] }
modify ({ "kind" => "section", "only" => ["default"] })
Should return config for selected section as in all['sections']:
{ 'sections }
add ( { "kind" => "section" }, { "type" => "image", "image" => "a", "initrd" => "b", "kernel_append" => "debug" })
modify ({ "kind" => "section", "id" => "cool section" }, { "append" => "more cool append" })
modify ({ "kind" => "global" }, { "default" => "cool section" })
Difference is that sections can have nested sections. Second one is that id of section isn't single id.
This is mainly about identifiers for such sections and how to represent it. My proposal is that id should not be just string...for nested section use array and for complex key use map
so it could look like that:
modify ({ "kind" => "section", "id" => [{"shared-network" => "224-29}, {"subnet" => "10.20.4.0" netmask =>"255.255.255.255"], {"host" => "fantasia"} }, { "fixed-address" => "example" })