Skip to content

Commit

Permalink
fix dep package manager & update docs (#6)
Browse files Browse the repository at this point in the history
* add entry for dep

* update docs
  • Loading branch information
yufeiminds authored Oct 15, 2018
1 parent 175ad0c commit ec07769
Show file tree
Hide file tree
Showing 8 changed files with 176 additions and 54 deletions.
3 changes: 2 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,8 @@ dep ensure -add github.com/ucloud/ucloud-sdk-go

- [Configure Document](./docs/Configure.md)
- [Usage Document](./docs/Usage.md)
- *Retry Policy (wait for writing)*
- [Retry Policy Document](./docs/Retry.md)
- [State Waiter Document](./docs/Wait.md)

## Feedback && Contributing

Expand Down
4 changes: 4 additions & 0 deletions doc.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/*
Package sdk is a toolkit for developer to create custom infrastructure via ucloud open api.
*/
package sdk
18 changes: 10 additions & 8 deletions docs/Configure.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
## Configure SDK
# Configure SDK

### Client Config
## Client Config

client config can control many common behaviors of sdk, it is required for any client.

#### Common Request Fields
### Common Request Fields

To set common region and project id for any request, you can also overwrite it by request.

Expand All @@ -15,7 +15,7 @@ cfg.Region = "cn-bj2"
cfg.ProjectId = "xxx"
```

#### Auto Retry
### Auto Retry

To enable auto-retry for any request, default is disabled(max retries is 0), it will auto retry for

Expand All @@ -26,7 +26,9 @@ To enable auto-retry for any request, default is disabled(max retries is 0), it
cfg.MaxRetries = 3
```

#### Logging
See [Retry Policy](./Retry.md) for more details.

### Logging

To set log level, you can see log with different level on **stdout**, you can also use it to enable or disable log.

Expand All @@ -39,15 +41,15 @@ cfg.LogLevel = log.PanicLevel
cfg.LogLevel = log.DebugLevel
```

#### Timeout
### Timeout

To set timeout for any network request, default is 30s.

```go
cfg.Timeout = 30 * time.Second
```

#### Internal Usage
### Internal Usage

the followed configuration should not be set in general usage.

Expand All @@ -57,7 +59,7 @@ To set User-Agent, you can append custom UserAgent for any request, it also used
cfg.UserAgent = "UCloud-CLI/0.1.0"
```

### Credential Config
## Credential Config

To set credential info for any request, credential is required for any client
```go
Expand Down
65 changes: 65 additions & 0 deletions docs/Retry.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Retry Policy

## How to enable retrying

Retrying feature is disabled by default.

hen retrying is enabled, such as client-level max retries is greater than 0 (enable retrying for all request), eg.

```go
cfg.MaxRetries = 3
```

or request-level max retries is greater than 0 (enable retrying for current request), eg.

```go
req.WithRetry(3)
```

## Retrying and side-effect

SDK has default retry policy to prevent retrying with side-effect. It will prevent most of action when follow term: ``create``, ``allocate``, ``clone``, ``copy`` is contained.

this actions will be set request-level retryable is false as default,

```go
req.SetRetryable(false)
```

you can set it to true to re-enable it simply.

```
req.SetRetryable(true)
```

Here is a table to show which action will prevent retrying by default:

| Action | Is Prevented |
| ----------------------- | ------------ |
| CreateUHostInstance ||
| CopyCustomImage ||
| CreateCustomImage ||
| AllocateEIP ||
| AllocateVIP ||
| CreateBandwidthPackage ||
| AllocateShareBandwidth ||
| CreateFirewall ||
| CreateULB ||
| CreateVServer ||
| CreatePolicy ||
| CreateSSL ||
| CreateVPC ||
| AddVPCNetwork ||
| CreateSubnet ||
| CreateVPCIntercom ||
| CreateRouteTable ||
| CloneRouteTable ||
| CreateUDisk ||
| CloneUDisk ||
| CreateProject ||
| CreateGlobalSSHInstance ||
| | |

## Example

You can see also [retry example](../examples/retry) for a full example.
93 changes: 93 additions & 0 deletions docs/Wait.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# State Waiter

SDK also provide state waiter helper to improver usage experience.

## Why use it?

Waiter can wait for remote state is achieved to target state. such as,

- create and wait for resource state is completed.
- invoke/start/stop a resource and wait for it is finished.
- custom retry policies and wait for retrying is finished.

## Usage

By the default, waiter will use exponential back-off delay between twice request. you can see [advanced options](#Advanced Options) for detail.

```go
waiter.StateWaiter{
Pending: []string{"pending"},
Target: []string{"avaliable"},
Refresh: CustomRefreshFn,
Timeout: 5 * time.Minute,
}
```

You can custom you own state machine from your own function. custom state refresh function should matched ``waiter.RefreshFunc``:

```go
type RefreshFunc func() (result interface{}, state string, err error)
```

seems like:

```go
func CustomRefreshFn() (interface{}, string, error) {
inst, err := describeUHostByID(uhostID)
if err != nil {
return nil, "", err
}

if inst == nil || inst.State != "Running" {
return nil, "pending", nil
}

return inst, "avaliable", nil
}
```

## Advanced Options

### Timeout

Timeout option will wait and refresh until target state or timeout is reached. State waiter use exponential back-off interval.

Option ``Timeout`` is required. By the default, max interval is 10s, if no other options is set, the refresh interval is:

```
0 100ms 200ms 400ms 800ms 1.6s 3.2s 6.4s 10s 10s
```

if ``MinTimeout`` is set, the refresh interval will start by a minimal value:

```
0 3s 6s 10s 10s ... (100ms < MinTimeout <= 10s, eg. 3s)
0 11s 10s 10s 10s ... (10s < MinTimeout, eg. 11s)
```

if ``PollInterval`` is set, the exponential back-off interval will be disabled. it will use simple poll interval instead.

```
0 3s 3s 3s 3s ... (PollInterval, eg. 3s)
```

### Delay

Delay option will wait until delay time is passed before first state is refreshed.

```go
waiter.StateWaiter{
Pending: []string{"pending"},
Target: []string{"avaliable"},
Refresh: CustomRefreshFn,
Timeout: 5 * time.Minute,
Delay: 30 * time.Second,
}
```

It is usually used in wait a little second after resource is created.

## Example

You can see also [wait for remote state example](../examples/wait) for a full example.
2 changes: 1 addition & 1 deletion examples/wait/README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# UCloud SDK Wait Example
# UCloud SDK Wait For Remote State Example

## What is the goal

Expand Down
43 changes: 0 additions & 43 deletions services/client.go

This file was deleted.

2 changes: 1 addition & 1 deletion ucloud/version/version.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@ package version

// Version is the version of sdk
// See also semantic version: https://semver.org/
const Version = "0.5.2"
const Version = "0.5.3"

0 comments on commit ec07769

Please sign in to comment.