fix: change policies API to return and take struct (#9181)

This allows for order guarantees in returned values can be consumed safely by the caller to avoid any additional parsing and validation. Fixes #9171
2025-12-07 16:22:33 -05:00 · 2020-04-07 19:30:59 -07:00
parent e7276b7b9b
commit 2642e12d14
16 changed files with 323 additions and 239 deletions
--- a/pkg/madmin/README.md
+++ b/pkg/madmin/README.md
@@ -71,7 +71,7 @@ __Parameters__
 ## 2. Service operations

 <a name="ServiceStatus"></a>
-### ServiceStatus() (ServiceStatusMetadata, error)
+### ServiceStatus(ctx context.Context) (ServiceStatusMetadata, error)
 Fetch service status, replies disk space used, backend type and total disks offline/online (applicable in distributed mode).

 | Param           | Type                    | Description                                                |
@@ -89,7 +89,7 @@ Fetch service status, replies disk space used, backend type and total disks offl

 ```go

-	st, err := madmClnt.ServiceStatus()
+	st, err := madmClnt.ServiceStatus(context.Background())
 	if err != nil {
 		log.Fatalln(err)
 	}
@@ -98,14 +98,14 @@ Fetch service status, replies disk space used, backend type and total disks offl
 ```

 <a name="ServiceRestart"></a>
-### ServiceRestart() error
+### ServiceRestart(ctx context.Context) error
 Sends a service action restart command to MinIO server.

 __Example__

 ```go
   // To restart the service, restarts all servers in the cluster.
-   err := madmClnt.ServiceRestart()
+   err := madmClnt.ServiceRestart(context.Background())
   if err != nil {
       log.Fatalln(err)
   }
@@ -113,14 +113,14 @@ Sends a service action restart command to MinIO server.
 ```

 <a name="ServiceStop"></a>
-### ServiceStop() error
+### ServiceStop(ctx context.Context) error
 Sends a service action stop command to MinIO server.

 __Example__

 ```go
   // To stop the service, stops all servers in the cluster.
-   err := madmClnt.ServiceStop()
+   err := madmClnt.ServiceStop(context.Background())
   if err != nil {
       log.Fatalln(err)
   }
@@ -128,7 +128,7 @@ Sends a service action stop command to MinIO server.
 ```

 <a name="ServiceTrace"></a>
-### ServiceTrace(allTrace bool, doneCh <-chan struct{}) <-chan TraceInfo
+### ServiceTrace(ctx context.Context, allTrace bool, doneCh <-chan struct{}) <-chan TraceInfo
 Enable HTTP request tracing on all nodes in a MinIO cluster

 __Example__
@@ -139,7 +139,7 @@ __Example__
    // listen to all trace including internal API calls
    allTrace := true
    // Start listening on all trace activity.
-    traceCh := madmClnt.ServiceTrace(allTrace, doneCh)
+    traceCh := madmClnt.ServiceTrace(context.Background(), allTrace, doneCh)
    for traceInfo := range traceCh {
        fmt.Println(traceInfo.String())
    }
@@ -148,7 +148,7 @@ __Example__
 ## 3. Info operations

 <a name="ServerInfo"></a>
-### ServerInfo() ([]ServerInfo, error)
+### ServerInfo(ctx context.Context) ([]ServerInfo, error)
 Fetches information for all cluster nodes, such as server properties, storage information, network statistics, etc.

 | Param                            | Type               | Description                                                        |
@@ -199,7 +199,7 @@ Fetches information for all cluster nodes, such as server properties, storage in

 ```go

-	serversInfo, err := madmClnt.ServerInfo()
+	serversInfo, err := madmClnt.ServerInfo(context.Background())
 	if err != nil {
 		log.Fatalln(err)
 	}
@@ -211,7 +211,7 @@ Fetches information for all cluster nodes, such as server properties, storage in
 ```

 <a name="ServerDrivesPerfInfo"></a>
-### ServerDrivesPerfInfo() ([]ServerDrivesPerfInfo, error)
+### ServerDrivesPerfInfo(ctx context.Context) ([]ServerDrivesPerfInfo, error)

 Fetches drive performance information for all cluster nodes.

@@ -229,7 +229,7 @@ Fetches drive performance information for all cluster nodes.
 | `disk.Performance.ReadSpeed`  | _float64_ | Read speed on above path in Bytes/s.                   |

 <a name="ServerCPULoadInfo"></a>
-### ServerCPULoadInfo() ([]ServerCPULoadInfo, error)
+### ServerCPULoadInfo(ctx context.Context) ([]ServerCPULoadInfo, error)

 Fetches CPU utilization for all cluster nodes.

@@ -247,7 +247,7 @@ Fetches CPU utilization for all cluster nodes.
 | `cpu.Load.Error` | _string_  | Error (if any) encountered while accessing the CPU info         |

 <a name="ServerMemUsageInfo"></a>
-### ServerMemUsageInfo() ([]ServerMemUsageInfo, error)
+### ServerMemUsageInfo(ctx context.Context) ([]ServerMemUsageInfo, error)

 Fetches Mem utilization for all cluster nodes.

@@ -263,7 +263,7 @@ Fetches Mem utilization for all cluster nodes.
 | `mem.Usage.Error` | _string_ | Error (if any) encountered while accessing the CPU info |

 <a name="NetPerfInfo"></a>
-### NetPerfInfo(int size) (map[string][]NetPerfInfo, error)
+### NetPerfInfo(ctx context.Context, int size) (map[string][]NetPerfInfo, error)

 Fetches network performance of all cluster nodes using given sized payload. Returned value is a map containing each node indexed list of performance of other nodes.

@@ -275,7 +275,7 @@ Fetches network performance of all cluster nodes using given sized payload. Retu


 <a name="ServerCPUHardwareInfo"></a>
-### ServerCPUHardwareInfo() ([]ServerCPUHardwareInfo, error)
+### ServerCPUHardwareInfo(ctx context.Context) ([]ServerCPUHardwareInfo, error)

 Fetches hardware information of CPU.

@@ -302,7 +302,7 @@ Fetches hardware information of CPU.
 | `CPUInfo.Microcode`        | _string_ | Micro codes                                            |

 <a name="ServerNetworkHardwareInfo"></a>
-### ServerNetworkHardwareInfo() ([]ServerNetworkHardwareInfo, error)
+### ServerNetworkHardwareInfo(ctx context.Context) ([]ServerNetworkHardwareInfo, error)

 Fetches hardware information of CPU.

@@ -321,7 +321,7 @@ Fetches hardware information of CPU.
 | `NetworkInfo.Flags`        | _uint32_ | e.g., FlagUp, FlagLoopback, FlagMulticast                 |

 <a name="StorageInfo"></a>
-### StorageInfo() (StorageInfo, error)
+### StorageInfo(ctx context.Context) (StorageInfo, error)

 Fetches Storage information for all cluster nodes.

@@ -347,7 +347,7 @@ __Example__

 ```go

-	storageInfo, err := madmClnt.StorageInfo()
+	storageInfo, err := madmClnt.StorageInfo(context.Background())
 	if err != nil {
 		log.Fatalln(err)
 	}
@@ -359,7 +359,7 @@ __Example__
 ## 5. Heal operations

 <a name="Heal"></a>
-### Heal(bucket, prefix string, healOpts HealOpts, clientToken string, forceStart bool, forceStop bool) (start HealStartSuccess, status HealTaskStatus, err error)
+### Heal(ctx context.Context, bucket, prefix string, healOpts HealOpts, clientToken string, forceStart bool, forceStop bool) (start HealStartSuccess, status HealTaskStatus, err error)

 Start a heal sequence that scans data under given (possible empty)
 `bucket` and `prefix`. The `recursive` bool turns on recursive
@@ -384,7 +384,7 @@ __Example__
    }
    forceStart := false
    forceStop := false
-    healPath, err := madmClnt.Heal("", "", opts, "", forceStart, forceStop)
+    healPath, err := madmClnt.Heal(context.Background(), "", "", opts, "", forceStart, forceStop)
    if err != nil {
        log.Fatalln(err)
    }
@@ -424,13 +424,13 @@ __Example__
 ## 6. Config operations

 <a name="GetConfig"></a>
-### GetConfig() ([]byte, error)
+### GetConfig(ctx context.Context) ([]byte, error)
 Get current `config.json` of a MinIO server.

 __Example__

 ``` go
-    configBytes, err := madmClnt.GetConfig()
+    configBytes, err := madmClnt.GetConfig(context.Background())
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }
@@ -447,14 +447,14 @@ __Example__


 <a name="SetConfig"></a>
-### SetConfig(config io.Reader) error
+### SetConfig(ctx context.Context, config io.Reader) error
 Set a new `config.json` for a MinIO server.

 __Example__

 ``` go
    config := bytes.NewReader([]byte(`config.json contents go here`))
-    if err := madmClnt.SetConfig(config); err != nil {
+    if err := madmClnt.SetConfig(context.Background(), config); err != nil {
        log.Fatalf("failed due to: %v", err)
    }
    log.Println("SetConfig was successful")
@@ -463,13 +463,13 @@ __Example__
 ## 7. Top operations

 <a name="TopLocks"></a>
-### TopLocks() (LockEntries, error)
+### TopLocks(ctx context.Context) (LockEntries, error)
 Get the oldest locks from MinIO server.

 __Example__

 ``` go
-    locks, err := madmClnt.TopLocks()
+    locks, err := madmClnt.TopLocks(context.Background())
    if err != nil {
        log.Fatalf("failed due to: %v", err)
    }
@@ -485,51 +485,54 @@ __Example__
 ## 8. IAM operations

 <a name="AddCannedPolicy"></a>
-### AddCannedPolicy(policyName string, policy string) error
+### AddCannedPolicy(ctx context.Context, policyName string, policy *iampolicy.Policy) error
 Create a new canned policy on MinIO server.

 __Example__

 ```
-	policy := `{"Version": "2012-10-17","Statement": [{"Action": ["s3:GetObject"],"Effect": "Allow","Resource": ["arn:aws:s3:::my-bucketname/*"],"Sid": ""}]}`
+	policy, err := iampolicy.ParseConfig(strings.NewReader(`{"Version": "2012-10-17","Statement": [{"Action": ["s3:GetObject"],"Effect": "Allow","Resource": ["arn:aws:s3:::my-bucketname/*"],"Sid": ""}]}`))
+    if err != nil {
+        log.Fatalln(err)
+    }

-    if err = madmClnt.AddCannedPolicy("get-only", policy); err != nil {
+    if err = madmClnt.AddCannedPolicy(context.Background(), "get-only", policy); err != nil {
 		log.Fatalln(err)
 	}
 ```

 <a name="AddUser"></a>
-### AddUser(user string, secret string) error
+### AddUser(ctx context.Context, user string, secret string) error
 Add a new user on a MinIO server.

 __Example__

 ``` go
-	if err = madmClnt.AddUser("newuser", "newstrongpassword"); err != nil {
+	if err = madmClnt.AddUser(context.Background(), "newuser", "newstrongpassword"); err != nil {
 		log.Fatalln(err)
 	}
 ```

 <a name="SetUserPolicy"></a>
-### SetUserPolicy(user string, policyName string) error
+### SetUserPolicy(ctx context.Context, user string, policyName string) error
 Enable a canned policy `get-only` for a given user on MinIO server.

 __Example__

 ``` go
-	if err = madmClnt.SetUserPolicy("newuser", "get-only"); err != nil {
+	if err = madmClnt.SetUserPolicy(context.Background(), "newuser", "get-only"); err != nil {
 		log.Fatalln(err)
 	}
 ```

 <a name="ListUsers"></a>
-### ListUsers() (map[string]UserInfo, error)
+### ListUsers(ctx context.Context) (map[string]UserInfo, error)
 Lists all users on MinIO server.

 __Example__

 ``` go
-	users, err := madmClnt.ListUsers();
+	users, err := madmClnt.ListUsers(context.Background());
    if err != nil {
 		log.Fatalln(err)
 	}
@@ -541,7 +544,7 @@ __Example__
 ## 9. Misc operations

 <a name="ServerUpdate"></a>
-### ServerUpdate(updateURL string) (ServerUpdateStatus, error)
+### ServerUpdate(ctx context.Context, updateURL string) (ServerUpdateStatus, error)
 Sends a update command to MinIO server, to update MinIO server to latest release. In distributed setup it updates all servers atomically.

 __Example__
@@ -549,7 +552,7 @@ Sends a update command to MinIO server, to update MinIO server to latest release
 ```go
   // Updates all servers and restarts all the servers in the cluster.
   // optionally takes an updateURL, which is used to update the binary.
-   us, err := madmClnt.ServerUpdate(updateURL)
+   us, err := madmClnt.ServerUpdate(context.Background(), updateURL)
   if err != nil {
       log.Fatalln(err)
   }
@@ -559,13 +562,13 @@ Sends a update command to MinIO server, to update MinIO server to latest release
 ```

 <a name="StartProfiling"></a>
-### StartProfiling(profiler string) error
+### StartProfiling(ctx context.Context, profiler string) error
 Ask all nodes to start profiling using the specified profiler mode

 __Example__

 ``` go
-    startProfilingResults, err = madmClnt.StartProfiling("cpu")
+    startProfilingResults, err = madmClnt.StartProfiling(context.Background(), "cpu")
    if err != nil {
            log.Fatalln(err)
    }
@@ -580,13 +583,13 @@ __Example__
 ```

 <a name="DownloadProfilingData"></a>
-### DownloadProfilingData() ([]byte, error)
+### DownloadProfilingData(ctx context.Context) ([]byte, error)
 Download profiling data of all nodes in a zip format.

 __Example__

 ``` go
-    profilingData, err := madmClnt.DownloadProfilingData()
+    profilingData, err := madmClnt.DownloadProfilingData(context.Background())
    if err != nil {
            log.Fatalln(err)
    }
@@ -614,7 +617,7 @@ __Example__
 ## 11. KMS

 <a name="GetKeyStatus"></a>
-### GetKeyStatus(keyID string) (*KMSKeyStatus, error)
+### GetKeyStatus(ctx context.Context, keyID string) (*KMSKeyStatus, error)
 Requests status information about one particular KMS master key
 from a MinIO server. The keyID is optional and the server will
 use the default master key (configured via `MINIO_KMS_VAULT_KEY_NAME`
@@ -623,7 +626,7 @@ or `MINIO_KMS_MASTER_KEY`) if the keyID is empty.
 __Example__

 ``` go
-    keyInfo, err := madmClnt.GetKeyStatus("my-minio-key")
+    keyInfo, err := madmClnt.GetKeyStatus(context.Background(), "my-minio-key")
    if err != nil {
       log.Fatalln(err)
    }