AOC Go SDK
AOC SDK for golang,required golang 1.18+
Installation
go get github.com/arcfraofficial/aoc-go-sdk
Usage
The examples use two helper libraries: pointy and go-funk. pointy can quickly create pointers to primitive types. Go-funk provides utility methods such as Map, Filter, Reduce, etc.
Create instance
Create ApiClient instance
import (
apiclient "github.com/arcfraofficial/aoc-go-sdk/client"
httptransport "github.com/go-openapi/runtime/client"
"github.com/go-openapi/strfmt"
)
transport := httptransport.New("aoc.example.com", "/v2/api", []string{"http"})
client := apiclient.New(transport, strfmt.Default)
If using self-signed certificate, use setVerifyingSsl to ignore ssl verification
import (
apiclient "github.com/arcfraofficial/aoc-go-sdk/client"
httptransport "github.com/go-openapi/runtime/client"
"github.com/go-openapi/strfmt"
)
tlsClient, err := httptransport.TLSClient(httptransport.TLSClientOptions{
InsecureSkipVerify: true,
})
if err != nil {
fmt.Print(err)
return
}
transport := httptransport.NewWithClient("aoc.example.com", "/v2/api", []string{"https"}, tlsClient)
client := apiclient.New(transport, strfmt.Default)
Sending request
depends on operation, import specific client package
import (
vm "github.com/arcfraofficial/aoc-go-sdk/client/vm"
)
Authentication
Use NewWithUserConfig to create an authenticated Client instance
import (
apiclient "github.com/arcfraofficial/aoc-go-sdk/client"
"github.com/arcfraofficial/aoc-go-sdk/models"
)
client, err := apiclient.NewWithUserConfig(apiclient.ClientConfig{
Host: "localhost:8090",
BasePath: "v2/api",
Schemes: []string{"http"},
}, apiclient.UserConfig{
Name: "<username>",
Password: "<password>",
Source: models.UserSourceLOCAL,
})
or mannual configure authenticate header after Client created
import (
User "github.com/arcfraofficial/aoc-go-sdk/client/user"
)
loginParams := User.NewLoginParams()
loginParams.RequestBody = &models.LoginInput{
Username: pointy.String("<username>"),
Password: pointy.String("<password>"),
Source: models.NewUserSource(models.UserSourceLOCAL),
}
logRes, err := client.User.Login(loginParams)
if err != nil {
return err
}
transport.DefaultAuthentication = httptransport.APIKeyAuth("Authorization", "header", *logRes.Payload.Data.Token)
List resource
getVmParams := vm.NewGetVmsParams();
getVmParams.RequestBody = &models.GetVmsRequestBody{
Where: &models.VMWhereInput{
ID: pointy.String("vm_id"),
},
}
vmsRes, err := client.VM.GetVms(getVmParams)
if err != nil {
return err
}
vms := vmsRes.Payload
Mutation
Mostly mutation will response as async task earlier to avoid request hanging when executing long-running operation.
target_vm := vmsRes.Payload[0]
vmStartParams := vm.NewStartVMParams()
vmStartParams.RequestBody = &models.VMStartParams{
Where: &models.VMWhereInput{
ID: target_vm.ID,
},
}
startRes, err := client.VM.StartVM(vmStartParams)
if err != nil {
return err
}
An utils function WaitTask is export from utils package
task := *startRes.Payload[0].TaskID
err = utils.WaitTask(context.TODO(), client, task, 1*time.Second)
if err != nil {
return err
}
Here is also WaitTasks function for waiting multiple task
tasks := funk.Map(startRes.Payload, func(tvm *models.WithTaskVM) string {
return *tvm.TaskID
}).([]string)
err = utils.WaitTasks(context.TODO(), client, tasks, 1*time.Second)
if err != nil {
return err
}
#### Create `ActivePassiveApiClient` instance
AOC introduced multi-management-IP active-passive deployment in version 4.9.0. To access such AOC deployments, you can use `ActivePassiveApiClient` to configure multiple endpoints for the same active-passive cluster. At any given time, it is expected that at most one active endpoint exists. The order of endpoints passed in does not represent the active-passive relationship; the client will select the current active endpoint based on probing results.
```go
import (
"context"
apiclient "github.com/arcfraofficial/aoc-go-sdk/client"
"github.com/arcfraofficial/aoc-go-sdk/models"
)
client, err := apiclient.NewActivePassiveWithUserConfig(
context.Background(),
apiclient.ActivePassiveClientConfig{
Endpoints: []apiclient.ActivePassiveEndpointConfig{
{Host: "aoc-a.example.com", Schemes: []string{"https"}},
{Host: "aoc-b.example.com", Schemes: []string{"https"}},
},
},
apiclient.UserConfig{
Name: "<username>",
Password: "<password>",
Source: models.UserSourceLOCAL,
},
)
if err != nil {
return err
}
Failover strategies
ActivePassiveApiClient supports the following failover strategies:
AUTO_FAILOVER: The default strategy. When there is no cached active endpoint, it attempts to probe and cache the current active endpoint; after a request returns 307, it automatically re-probes and retries once; after a network I/O exception occurs, it clears the cache but does not automatically retry.
MANUAL_FAILOVER: After a request returns 307, it does not automatically re-probe or retry. Clearing the cache is handled by the caller for failover. The rest of the business logic is consistent with AUTO_FAILOVER.
ALWAYS_PROBE: Does not cache the active endpoint. Re-probes the active endpoint before each request; after a request returns 307, it does not automatically retry.
If you need to specify a failover strategy, you can pass it in when creating the instance:
client, err := apiclient.NewActivePassiveWithUserConfig(
context.Background(),
apiclient.ActivePassiveClientConfig{
Endpoints: []apiclient.ActivePassiveEndpointConfig{
{Host: "aoc-a.example.com", Schemes: []string{"https"}},
{Host: "aoc-b.example.com", Schemes: []string{"https"}},
},
FailoverStrategy: apiclient.FailoverStrategyManualFailover,
},
apiclient.UserConfig{
Name: "<username>",
Password: "<password>",
Source: models.UserSourceLOCAL,
},
)
if err != nil {
return err
}