Migrazione a v3

​

In sintesi

​

Costruzione e opzioni

-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

​

Metodo per metodo

​

Tipi

​

Errori

// 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
}

• I fallimenti di rete ora sono *APIError con Status 0, Code NETWORK_ERROR o TIMEOUT e il testo della causa come Message, e fanno l’unwrap alla causa (errors.Is(err, context.Canceled) funziona).
• Lo stesso vale per i controlli locali (Status 0: INVALID_ID, FILE_TOO_LARGE, INVALID_API_KEY) e per un body 2xx che non è JSON (UNKNOWN_ERROR, Invalid JSON in HTTP <status> response).
• Un body 2xx che contiene "status": "error" ora è un errore (la v2 lo segnalava come successo). I rifiuti del cluster all’avvio/arresto di app e database arrivano come 409 CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT o ACTION_FAILED, senza messaggio. L’SDK restituisce una risposta “already” come errore: trattala tu come successo, se necessario.
• Una risposta senza codice ha Code UNKNOWN_ERROR.
• Una chiave API scaduta produce 401 ACCESS_DENIED, come una sconosciuta.
• Esiste una costante Code* per ogni codice documentato dall’API. L’API ora invia 429 RATE_LIMITED (CodeRateLimited) dove prima inviava RATE_LIMIT e RATE_LIMIT_EXCEEDED; CodeRateLimit e CodeRateLimitExceeded restano, deprecati.
• Ogni errore di AI.Chat ha la forma di OpenAI con un codice minuscolo (access_denied, rate_limit_exceeded, server_overloaded, …), che Code riporta testualmente.
• Error() produce squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> (v2: squarecloud: <message> (<CODE>, HTTP <status>)). Basati sui campi, non sul testo.

​

Cambiamenti di comportamento

• Chiave API vuota: New("") (o una chiave composta solo da spazi) restituisce comunque un client (non può restituire un errore), ma ogni chiamata tranne Service.Status fallisce localmente con INVALID_API_KEY.
• Snapshot 202: la v2 restituiva un *APIError con StatusCode 202. La v3 restituisce un SnapshotCreated con Pending: true e un errore nil.
• Realtime: Next ora restituisce un RealtimeEvent. Usa uno switch su ev.Event (system, status, logs, error, message). Per i log, stampa ev.Line (il byte \u0001/\u0002 viene rimosso; ev.Data resta il frame grezzo) e usa ev.Stream per stdout/stderr. Per lo stato, usa ev.Status: mai nil in un evento di stato, unito in modo superficiale tra frame e riconnessioni. Dopo REALTIME_DISCONNECTED, Next restituisce io.EOF. Il flusso non si interrompe più dopo 30 s, le riconnessioni attendono almeno 5,5 s dopo l’apertura precedente, e l’apertura è limitata dal timeout del client fino all’arrivo degli header. Vedi Realtime.
• Timeout: la v2 usava un timeout fisso di 30 s dell’http.Client per tutto. La v3 applica una scadenza predefinita solo quando ctx non ne ha una: il timeout del client (WithTimeout, 30 s) per la maggior parte delle chiamate; almeno 2 minuti per start/stop/restart, creazione di database, creazione/ripristino di snapshot e AI.Chat; nessuna per upload, scritture di file con contenuto oltre 1 MiB e download di snapshot. WithTimeout(0) le disattiva tutte.
• Finestre di rete vuote: Analytics, Errors e Performance restituiscono puntatori nil quando la finestra non ha traffico.
• Header: ogni richiesta all’API invia Accept: application/json (text/event-stream per il realtime). Lo User-Agent predefinito è cambiato da Square GO a squarecloud-sdk-go/3.0.0 (WithUserAgent lo sostituisce ancora).
• Id: ogni id ora è codificato in percent-encoding come un singolo segmento del percorso (la v2 lo inseriva nel percorso così com’era), e un id vuoto, . o .. fallisce localmente con INVALID_ID.
• Scrittura di file: la v2 inviava sempre il contenuto come stringa, cosa che corrompeva i file binari, e non poteva scrivere un file vuoto. La v3 invia sempre il contenuto codificato in base64, quindi ogni byte resta identico, un contenuto vuoto scrive un file vuoto e un contenuto oltre 10 MB fallisce localmente con FILE_TOO_LARGE. L’API risponde 400 INVALID_CONTENT per un contenuto che non riesce a decodificare.
• Lettura di file: la v3 richiede sempre base64 e lo decodifica, invece dell’array di byte JSON letto dalla v2 (che l’API ha deprecato). Un file oltre 10 MB produce 413 FILE_TOO_LARGE.
• Elenco dei file: elencare una directory che non esiste produce 404 FILE_NOT_FOUND; prima era un elenco vuoto.
• Snapshot: le voci dell’elenco contengono VersionID e URL forniti dall’API; non viene estratto nulla da Key.
• Retry: novità. Gli errori di rete delle GET, i 503 UPLOAD_BUSY/ANALYTICS_BUSY e i 503 DATABASE_UNAVAILABLE sulle GET vengono ripetuti due volte per impostazione predefinita; WithMaxRetries(0) ripristina il comportamento della v2. DATABASE_UNAVAILABLE può arrivare dopo che una mutazione è iniziata, quindi l’SDK non lo ripete mai sugli altri metodi; ripeti tu una mutazione idempotente, se vuoi. Vedi Retry.
• Versione di Go: il minimo è sceso da Go 1.24 a Go 1.22.