Skip to content

Commit

Permalink
Merge pull request #25 from cobbler/docs/add-godoc
Browse files Browse the repository at this point in the history 
Docs: Add method documentation
  • Loading branch information
@SchoolGuy
SchoolGuy committed Jun 5, 2024
2 parents a7e3844 + b8a5edd commit 20c493c
Show file tree
Hide file tree
Showing 15 changed files with 161 additions and 135 deletions.
19 changes: 11 additions & 8 deletions actions.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ func (c *Client) Sync() error {
return err
}

// BackgroundSync will run a "cobbler sync" in asynchronously in the background. The returned string is the event id
// BackgroundSync runs a "cobbler sync" in asynchronously in the background. The returned string is the event id
// which can be used to query the GetEventLog endpoint.
func (c *Client) BackgroundSync(options BackgroundSyncOptions) (string, error) {
res, err := c.Call("background_sync", options, c.Token)
Expand All @@ -18,7 +18,7 @@ func (c *Client) BackgroundSync(options BackgroundSyncOptions) (string, error) {
}
}

// BackgroundSyncSystems will run the "cobbler syncsystems" action which only executes a Cobbler sync for a specific
// BackgroundSyncSystems runs the "cobbler syncsystems" action which only executes a Cobbler sync for a specific
// subset of systems.
func (c *Client) BackgroundSyncSystems(options BackgroundSyncSystemsOptions) (string, error) {
res, err := c.Call("background_syncsystems", options, c.Token)
Expand All @@ -29,7 +29,7 @@ func (c *Client) BackgroundSyncSystems(options BackgroundSyncSystemsOptions) (st
}
}

// Check will run the "cobbler check" action and list all possible points for improvements on server side as a
// Check runs the "cobbler check" action and list all possible points for improvements on server side as a
// return value.
func (c *Client) Check() (*[]string, error) {
var checks []string
Expand All @@ -42,7 +42,7 @@ func (c *Client) Check() (*[]string, error) {
return &checks, err
}

// BackgroundBuildiso will build an ISO file on the server. The return value is the task ID which is started on the
// BackgroundBuildiso builds an ISO file on the server. The return value is the task ID which is started on the
// server.
func (c *Client) BackgroundBuildiso(options BuildisoOptions) (string, error) {
result, err := c.Call("background_buildiso", options, c.Token)
Expand All @@ -53,7 +53,7 @@ func (c *Client) BackgroundBuildiso(options BuildisoOptions) (string, error) {
}
}

// BackgroundAclSetup will apply updated ACLs on the Cobbler system.
// BackgroundAclSetup applies updated ACLs on the Cobbler system.
func (c *Client) BackgroundAclSetup(options AclSetupOptions) (string, error) {
result, err := c.Call("background_aclsetup", options, c.Token)
if err != nil {
Expand All @@ -63,7 +63,7 @@ func (c *Client) BackgroundAclSetup(options AclSetupOptions) (string, error) {
}
}

// BackgroundHardlink will try to save space inside the web directory through hardlinking identical files.
// BackgroundHardlink tries to save space inside the web directory through hardlinking identical files.
func (c *Client) BackgroundHardlink() (string, error) {
result, err := c.Call("background_hardlink", map[string]string{}, c.Token)
if err != nil {
Expand All @@ -73,7 +73,7 @@ func (c *Client) BackgroundHardlink() (string, error) {
}
}

// BackgroundValidateAutoinstallFiles will check if the files generated by Cobbler are valid from a syntax perspective.
// BackgroundValidateAutoinstallFiles checks if the files generated by Cobbler are valid from a syntax perspective.
func (c *Client) BackgroundValidateAutoinstallFiles() (string, error) {
result, err := c.Call("background_validate_autoinstall_files", map[string]string{}, c.Token)
if err != nil {
Expand All @@ -83,7 +83,7 @@ func (c *Client) BackgroundValidateAutoinstallFiles() (string, error) {
}
}

// BackgroundReplicate will replicate the Cobbler server to the target defined in the arguments.
// BackgroundReplicate replicates the Cobbler server to the target defined in the arguments.
func (c *Client) BackgroundReplicate(options ReplicateOptions) (string, error) {
result, err := c.Call("background_replicate", options, c.Token)
if err != nil {
Expand All @@ -93,6 +93,7 @@ func (c *Client) BackgroundReplicate(options ReplicateOptions) (string, error) {
}
}

// BackgroundImport runs an import locally on the server with the specified options.
func (c *Client) BackgroundImport(options BackgroundImportOptions) (string, error) {
result, err := c.Call("background_import", options, c.Token)
if err != nil {
Expand All @@ -102,6 +103,7 @@ func (c *Client) BackgroundImport(options BackgroundImportOptions) (string, erro
}
}

// BackgroundReposync runs a reposyonc asynchronous in the background on the server.
func (c *Client) BackgroundReposync(options BackgroundReposyncOptions) (string, error) {
result, err := c.Call("background_reposync", options, c.Token)
if err != nil {
Expand All @@ -111,6 +113,7 @@ func (c *Client) BackgroundReposync(options BackgroundReposyncOptions) (string,
}
}

// BackgroundMkLoaders runs the mkloaders action on the server in the background.
func (c *Client) BackgroundMkLoaders() (string, error) {
result, err := c.Call("background_mkloaders", map[string]string{}, c.Token)
if err != nil {
Expand Down
17 changes: 9 additions & 8 deletions authentication.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,8 @@ func convertToInt(integer interface{}) (int, error) {
}
}

// CheckAccessNoFail is ...
// CheckAccessNoFail validates if a certain resource can be accessed with the current token. "arg1" and "arg2" have
// different meanings depending on the authorization provider configured server side.
func (c *Client) CheckAccessNoFail(resource, arg1, arg2 string) (bool, error) {
result, err := c.Call("check_access_no_fail", c.Token, resource, arg1, arg2)
if err != nil {
Expand All @@ -41,7 +42,8 @@ func (c *Client) CheckAccessNoFail(resource, arg1, arg2 string) (bool, error) {
}
}

// CheckAccess is ...
// CheckAccess performs the same check as [Client.CheckAccessNoFail] but returning the error message with the
// reason instead of a boolean.
func (c *Client) CheckAccess(resource, arg1, arg2 string) (int, error) {
result, err := c.Call("check_access", c.Token, resource, arg1, arg2)
if err != nil {
Expand All @@ -62,7 +64,7 @@ func (c *Client) CheckAccess(resource, arg1, arg2 string) (int, error) {
}
}

// GetAuthnModuleName is ...
// GetAuthnModuleName retrieves the currently configured authentication module name.
func (c *Client) GetAuthnModuleName() (string, error) {
result, err := c.Call("get_authn_module_name", c.Token)
if err != nil {
Expand All @@ -72,8 +74,7 @@ func (c *Client) GetAuthnModuleName() (string, error) {
}
}

// Login will perform a login request to Cobbler using the credentials provided
// in the configuration in the initializer.
// Login performs a login request to Cobbler using the credentials provided in the configuration in the initializer.
func (c *Client) Login() (bool, error) {
result, err := c.Call("login", c.config.Username, c.config.Password)
if err != nil {
Expand All @@ -84,7 +85,7 @@ func (c *Client) Login() (bool, error) {
return true, nil
}

// Logout is ...
// Logout performs a logout from the Cobbler server.
func (c *Client) Logout() (bool, error) {
result, err := c.Call("logout", c.Token)
if err != nil {
Expand All @@ -94,7 +95,7 @@ func (c *Client) Logout() (bool, error) {
}
}

// TokenCheck is ...
// TokenCheck returns if a given token is still valid or not.
func (c *Client) TokenCheck(token string) (bool, error) {
result, err := c.Call("token_check", token)
if err != nil {
Expand All @@ -104,7 +105,7 @@ func (c *Client) TokenCheck(token string) (bool, error) {
}
}

// GetUserFromToken is ...
// GetUserFromToken checks what user a given token is belonging to.
func (c *Client) GetUserFromToken(token string) (string, error) {
result, err := c.Call("get_user_from_token", token)
if err != nil {
Expand Down
65 changes: 37 additions & 28 deletions cobblerclient.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -31,16 +31,19 @@ import (

const bodyTypeXML = "text/xml"

// HTTPClient is ...
// HTTPClient is the interface which defines the API required for the [Client] to work correctly. Normally this
// is satisfied by a [http.DefaultClient].
type HTTPClient interface {
Post(string, string, io.Reader) (*http.Response, error)
}

// Client is ...
// Client is the type which all API methods are attached to.
type Client struct {
httpClient HTTPClient
config ClientConfig
Token string
// The longevity of this token is defined server side in the setting "auth_token_duration". Per default no token is
// retrieved. A token can be obtained via the [Client.Login] method.
Token string
}

// ClientConfig is the URL of Cobbler plus login credentials.
Expand All @@ -50,15 +53,16 @@ type ClientConfig struct {
Password string
}

// NewClient is ...
// NewClient creates a [Client] struct which is ready for usage.
func NewClient(httpClient HTTPClient, c ClientConfig) Client {
return Client{
httpClient: httpClient,
config: c,
}
}

// Call is ...
// Call is the generic method for calling an XML-RPC endpoint in Cobbler that has no dedicated method in the client.
// Normally there should be no need to use this if you are just using the client.
func (c *Client) Call(method string, args ...interface{}) (interface{}, error) {
var result interface{}

Expand Down Expand Up @@ -91,7 +95,7 @@ func (c *Client) Call(method string, args ...interface{}) (interface{}, error) {
return result, nil
}

// GenerateAutoinstall is ...
// GenerateAutoinstall generates the autoinstallation file for a given profile or system.
func (c *Client) GenerateAutoinstall(profile string, system string) (string, error) {
result, err := c.Call("generate_autoinstall", profile, system)
if err != nil {
Expand All @@ -101,7 +105,7 @@ func (c *Client) GenerateAutoinstall(profile string, system string) (string, err
}
}

// LastModifiedTime is ...
// LastModifiedTime retrieves the timestamp when any object in Cobbler was last modified.
func (c *Client) LastModifiedTime() (float64, error) {
result, err := c.Call("last_modified_time")
if err != nil {
Expand All @@ -111,7 +115,7 @@ func (c *Client) LastModifiedTime() (float64, error) {
}
}

// Ping is ...
// Ping is a simple method to check if the XML-RPC API is available.
func (c *Client) Ping() (bool, error) {
result, err := c.Call("ping")
if err != nil {
Expand All @@ -121,121 +125,126 @@ func (c *Client) Ping() (bool, error) {
}
}

// AutoAddRepos is ...
// AutoAddRepos automatically imports any repos server side that are known to the daemon. It is the responsitbility
// of the caller to execute [Client.BackgroundReposync].
func (c *Client) AutoAddRepos() error {
_, err := c.Call("auto_add_repos", c.Token)
return err
}

// GetAutoinstallTemplates is ...
// GetAutoinstallTemplates retrieves a list of all templates that are in use by Cobbler.
func (c *Client) GetAutoinstallTemplates() error {
_, err := c.Call("get_autoinstall_templates", c.Token)
return err
}

// GetAutoinstallSnippets is ...
// GetAutoinstallSnippets retrieves a list of all snippets that are in use by Cobbler.
func (c *Client) GetAutoinstallSnippets() error {
_, err := c.Call("get_autoinstall_snippets", c.Token)
return err
}

// IsAutoinstallInUse is ...
// IsAutoinstallInUse checks if a given system has reported that it is currently installing.
func (c *Client) IsAutoinstallInUse(name string) error {
_, err := c.Call("is_autoinstall_in_use", name, c.Token)
return err
}

// GenerateIPxe is ...
// GenerateIPxe generates the iPXE (formerly gPXE) configuration data.
func (c *Client) GenerateIPxe(profile, image, system string) error {
_, err := c.Call("generate_ipxe", profile, image, system)
return err
}

// GenerateBootCfg is ...
// GenerateBootCfg generates the bootcfg for a given MS Windows profile or system.
func (c *Client) GenerateBootCfg(profile, system string) error {
_, err := c.Call("generate_bootcfg", profile, system)
return err
}

// GenerateScript is ...
// GenerateScript generates for either a profile or sytem the requested script.
func (c *Client) GenerateScript(profile, system, name string) error {
_, err := c.Call("generate_script", profile, system, name)
return err
}

// GetBlendedData is ...
// GetBlendedData passes a profile or system through Cobblers inheritance chain and returns the result.
func (c *Client) GetBlendedData(profile, system string) error {
_, err := c.Call("get_blended_data", profile, system)
return err
}

// GetSettings is ...
// GetSettings returns the currently active settings.
func (c *Client) GetSettings() error {
_, err := c.Call("get_settings", c.Token)
return err
}

// RegisterNewSystem is ...
// RegisterNewSystem registers a new system without a Cobbler token. This is normally called
// during unattended installation by a script.
func (c *Client) RegisterNewSystem(info map[string]interface{}) error {
_, err := c.Call("register_new_system", info, c.Token)
return err
}

// RunInstallTriggers is ...
// RunInstallTriggers runs installation triggers for a given object. This is normally called during
// unattended installation.
func (c *Client) RunInstallTriggers(mode string, objtype string, name string, ip string) error {
_, err := c.Call("run_install_triggers", mode, objtype, name, ip, c.Token)
return err
}

// Version is ...
// Version is a shorter and easier version representation. Normally you want to call [Client.ExtendedVersion].
func (c *Client) Version() (float64, error) {
res, err := c.Call("version")
return res.(float64), err
}

// ExtendedVersion is ...
// ExtendedVersion returns the version information of the server.
func (c *Client) ExtendedVersion() error {
// FIXME: Parse and return result.
_, err := c.Call("extended_version")
return err
}

// GetReposCompatibleWithProfile is ...
// GetReposCompatibleWithProfile returns all repositories that can be potentially assigned to a given profile.
func (c *Client) GetReposCompatibleWithProfile(profile_name string) error {
_, err := c.Call("get_repos_compatible_with_profile", profile_name, c.Token)
return err
}

// FindSystemByDnsName is ...
// FindSystemByDnsName searches for a system with a given DNS name.
func (c *Client) FindSystemByDnsName(dns_name string) error {
_, err := c.Call("find_system_by_dns_name", dns_name)
return err
}

// GetRandomMac is ...
// GetRandomMac generates a random MAC address for use with a virtualized system.
func (c *Client) GetRandomMac() error {
_, err := c.Call("get_random_mac")
return err
}

// XmlRpcHacks is ...
// XmlRpcHacks is an internal endpoint that doesn't make sense to be called externally.
func (c *Client) XmlRpcHacks(data interface{}) error {
// FIXME: Make private server-side and remove from here.
_, err := c.Call("xmlrpc_hacks", data)
return err
}

// GetStatus is ...
// GetStatus retrieves the current status of installation progress that has been reported to Cobbler.
func (c *Client) GetStatus(mode string) error {
_, err := c.Call("get_status", mode, c.Token)
return err
}

// SyncDhcp is ...
// SyncDhcp updates the DHCP configuration synchronous.
func (c *Client) SyncDhcp() error {
_, err := c.Call("sync_dhcp", c.Token)
return err
}

// GetConfigData is ...
// GetConfigData retrieves configuration data for a given host.
func (c *Client) GetConfigData(hostname string) error {
_, err := c.Call("get_config_data", hostname)
return err
Expand Down

0 comments on commit 20c493c

Please sign in to comment.