# AWS Server Go SDK

供其他 Go 应用通过应用密钥调用 AWS Server 平台，完成 EC2 创建、价格预估和完整生命周期管理。SDK 只使用稳定的 `/api/sdk/v1` 接口，不需要也不会接触管理员 Token、AWS 账号 ID 或 AWS 凭证。

## 安装

```bash
go get gitea.s1f.ren/shiran/aws-server-sdk@v0.1.0
```

## 初始化

```go
client, err := awsserversdk.NewClient(
    "https://aws.example.com",
    os.Getenv("AWS_SERVER_APP_TOKEN"),
)
```

管理员需要先在平台创建客户端应用，为应用配置允许的 Region、权限范围和网络位置，并创建一次性显示的应用 Token。

## 完整创建流程

```go
ctx := context.Background()

options, err := client.Catalog.GetCreateOptions(ctx, "ap-northeast-1")
if err != nil {
    log.Fatal(err)
}

estimate, err := client.Pricing.EstimateInstance(ctx, "ap-northeast-1", awsserversdk.CreateInstanceRequest{
    PlacementID: options.Placements[0].PlacementID,
    ImageID: options.Images[0].ImageID,
    InstanceType: options.InstanceTypes[0].InstanceType,
    RootVolume: &awsserversdk.VolumeSpec{SizeGiB: 30, Type: "gp3"},
    AssociateEIP: true,
})
if err != nil {
    log.Fatal(err)
}
log.Printf("hourly=%f calendar_month=%f %s", estimate.HourlyPrice, estimate.CalendarMonthPrice, estimate.Currency)

operation, err := client.Instances.Create(ctx, "ap-northeast-1", awsserversdk.CreateInstanceRequest{
    PlacementID: options.Placements[0].PlacementID,
    ImageID: options.Images[0].ImageID,
    InstanceType: options.InstanceTypes[0].InstanceType,
    Name: "sdk-created",
    RootVolume: &awsserversdk.VolumeSpec{SizeGiB: 30, Type: "gp3"},
    SecurityGroupMode: "common_ports",
    AssociateEIP: true,
})
if err != nil {
    log.Fatal(err)
}
task, err := operation.Wait(ctx)
```

创建接口不接受 `account_id` 和 `subnet_id`。可以传管理员配置的 `placement_id`；省略时由平台选择可用网络位置。

## 实例管理

```go
instances, _ := client.Instances.List(ctx, region, awsserversdk.InstanceListOptions{Limit: 50})
details, _ := client.Instances.GetDetails(ctx, region, instanceID)

stop, _ := client.Instances.Stop(ctx, region, instanceID)
_, _ = stop.Wait(ctx)
resize, _ := client.Instances.Resize(ctx, region, instanceID, awsserversdk.ResizeInstanceRequest{InstanceType: "t3.small"})
_, _ = resize.Wait(ctx)
rebuild, _ := client.Instances.Rebuild(ctx, region, instanceID, awsserversdk.RebuildInstanceRequest{ImageID: "ami-..."})
_, _ = rebuild.Wait(ctx)
```

其他服务入口：

- `SecurityGroups`：查看、添加和删除安全组规则。
- `Volumes`：创建、挂载、卸载、扩容和删除数据卷。
- `EIPs`：申请或更换 EIP、设置 PTR 反向解析。
- `Traffic`：查询和修改实例出站流量额度。
- `Access`：登录信息、密码轮换和 SSH Key；需要敏感权限。
- `Agent`：Agent 状态、命令、升级、MOTD 和 SSH 审计。
- `Tasks`：应用自身任务的分页查询和等待。

所有修改方法接受可选的 `WithIdempotencyKey`。省略时 SDK 自动生成，并在网络重试中始终复用同一个值。

## 错误与敏感信息

```go
if awsserversdk.IsBudgetExceeded(err) { /* 提示额度不足 */ }
if awsserversdk.IsUnauthorized(err) { /* 检查 Token、权限范围或 Region */ }
```

密码和私钥使用 `Secret` 类型，日志和 JSON 序列化默认显示 `[REDACTED]`。只有显式调用 `Reveal()` 才能取得明文。

## 兼容性

- SDK `v0.x` 对应平台 `/api/sdk/v1`。
- 服务端可以增加响应字段；SDK 会忽略未知字段。
- 首版异步结果使用任务轮询，不提供 Webhook。