Migrando para a v3

​

Visão geral

​

Construção e opções

-import (
-	"github.com/squarecloudofc/sdk-api-go/v2/rest"
-	"github.com/squarecloudofc/sdk-api-go/v2/squarecloud"
-)
-client := rest.NewClient(token, rest.WithUserAgent(ua), rest.WithLogger(logger))
-api := rest.New(client)
-defer client.Close()
+import "github.com/squarecloudofc/sdk-api-go/v3"
+
+c := squarecloud.New(token, squarecloud.WithUserAgent(ua))

go get github.com/squarecloudofc/sdk-api-go/v3@v3.0.0

​

Método a método

​

Tipos

​

Erros

// v2
if rest.IsRateLimit(err) { ... }

// v3
var apiErr *squarecloud.APIError
if errors.As(err, &apiErr) && apiErr.Status == 429 {
	fmt.Println(apiErr.Code, apiErr.Message) // KEEP_CALM or RATE_LIMITED
}

• Falhas de rede agora são *APIError com Status 0, Code NETWORK_ERROR ou TIMEOUT e o texto da causa como Message, e fazem unwrap para a causa (errors.Is(err, context.Canceled) funciona).
• O mesmo vale para as verificações locais (Status 0: INVALID_ID, FILE_TOO_LARGE, INVALID_API_KEY) e para um corpo 2xx que não é JSON (UNKNOWN_ERROR, Invalid JSON in HTTP <status> response).
• Um corpo 2xx que diz "status": "error" agora é um erro (a v2 o reportava como sucesso). As recusas do cluster ao iniciar/parar aplicações e bancos de dados chegam como 409 CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT ou ACTION_FAILED, sem mensagem. O SDK retorna uma resposta “já” como erro: trate-a como sucesso por conta própria se precisar.
• Uma resposta sem código tem Code UNKNOWN_ERROR.
• Uma chave de API expirada resulta em 401 ACCESS_DENIED, como uma desconhecida.
• Há uma constante Code* para cada código que a API documenta. A API agora envia 429 RATE_LIMITED (CodeRateLimited) onde enviava RATE_LIMIT e RATE_LIMIT_EXCEEDED; CodeRateLimit e CodeRateLimitExceeded continuam existindo, depreciados.
• Todo erro de AI.Chat segue o formato da OpenAI, com um código em minúsculas (access_denied, rate_limit_exceeded, server_overloaded, …), que Code carrega literalmente.
• Error() gera squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> (v2: squarecloud: <message> (<CODE>, HTTP <status>)). Compare pelos campos, não pelo texto.

​

Mudanças de comportamento

• Chave de API vazia: New("") (ou uma chave composta apenas de espaços) ainda retorna um cliente (ele não pode retornar um erro), mas toda chamada, exceto Service.Status, falha localmente com INVALID_API_KEY.
• Snapshot 202: a v2 retornava um *APIError com StatusCode 202. A v3 retorna um SnapshotCreated com Pending: true e um erro nil.
• Realtime: Next agora retorna um RealtimeEvent. Faça um switch em ev.Event (system, status, logs, error, message). Para logs, imprima ev.Line (o byte \u0001/\u0002 é removido; ev.Data permanece o frame bruto) e use ev.Stream para stdout/stderr. Para status, use ev.Status: nunca nil em um evento de status, mesclado superficialmente entre frames e reconexões. Após REALTIME_DISCONNECTED, Next retorna io.EOF. O stream não morre mais após 30 s, as reconexões esperam pelo menos 5,5 s após a abertura anterior, e a abertura é limitada pelo timeout do cliente até os headers chegarem. Veja Tempo real.
• Timeouts: a v2 usava um timeout fixo de 30 s no http.Client para tudo. A v3 aplica um prazo padrão apenas quando o ctx não tem nenhum: o timeout do cliente (WithTimeout, 30 s) para a maioria das chamadas; pelo menos 2 minutos para start/stop/restart, criação de bancos de dados, criação/restauração de snapshots e AI.Chat; nenhum para uploads, escritas de arquivos com mais de 1 MiB de conteúdo e downloads de snapshots. WithTimeout(0) desativa todos eles.
• Janelas de rede vazias: Analytics, Errors e Performance retornam ponteiros nil quando a janela não tem tráfego.
• Headers: toda requisição à API envia Accept: application/json (text/event-stream para realtime). O User-Agent padrão mudou de Square GO para squarecloud-sdk-go/3.0.0 (WithUserAgent ainda o substitui).
• Ids: todo id agora é codificado com percent-encoding como um único segmento de caminho (a v2 o colava no caminho como estava), e um id vazio, . ou .. falha localmente com INVALID_ID.
• Escrita de arquivos: a v2 sempre enviava o conteúdo como string, o que corrompia arquivos binários, e não conseguia escrever um arquivo vazio. A v3 sempre envia o conteúdo codificado em base64, então todo byte chega intacto, conteúdo vazio escreve um arquivo vazio, e conteúdo acima de 10 MB falha localmente com FILE_TOO_LARGE. A API responde 400 INVALID_CONTENT para conteúdo que não consegue decodificar.
• Leitura de arquivos: a v3 sempre solicita base64 e o decodifica, em vez do array de bytes JSON que a v2 lia (que a API depreciou). Um arquivo acima de 10 MB resulta em 413 FILE_TOO_LARGE.
• Listagem de arquivos: listar um diretório que não existe resulta em 404 FILE_NOT_FOUND; antes era uma lista vazia.
• Snapshots: as entradas da listagem trazem VersionID e URL vindos da API; nada é extraído de Key.
• Novas tentativas: novidade. Erros de rede em GET, 503 UPLOAD_BUSY/ANALYTICS_BUSY e 503 DATABASE_UNAVAILABLE em GET são tentados novamente duas vezes por padrão; WithMaxRetries(0) restaura o comportamento da v2. DATABASE_UNAVAILABLE pode chegar depois que uma mutação já começou, então o SDK nunca o repete em outros métodos; repita uma mutação idempotente por conta própria se quiser. Veja Novas tentativas.
• Versão do Go: o mínimo caiu do Go 1.24 para o Go 1.22.