Migrer vers la v3

​

En un coup d’œil

​

Construction et options

-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éthode par méthode

​

Types

​

Erreurs

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

• Les échecs réseau sont désormais des *APIError avec Status 0, Code NETWORK_ERROR ou TIMEOUT et le texte de la cause comme Message, et ils encapsulent la cause (errors.Is(err, context.Canceled) fonctionne).
• Il en va de même pour les vérifications locales (Status 0 : INVALID_ID, FILE_TOO_LARGE, INVALID_API_KEY) et pour un corps 2xx qui n’est pas du JSON (UNKNOWN_ERROR, Invalid JSON in HTTP <status> response).
• Un corps 2xx indiquant "status": "error" est désormais une erreur (la v2 le signalait comme un succès). Les refus du cluster lors du démarrage ou de l’arrêt des applications et des bases de données arrivent en 409 CONTAINER_ALREADY_STARTED, CONTAINER_ALREADY_STOPPED, CONTAINER_TEMPORARILY_SUSPENDED, CONTAINER_NOT_FOUND, CONTAINER_INSUFFICIENT_DISK_SPACE, CONTAINER_NETWORK_CONFLICT ou ACTION_FAILED, sans message. Le SDK renvoie une réponse « déjà » comme une erreur : traitez-la vous-même comme un succès si nécessaire.
• Une réponse sans code a le Code UNKNOWN_ERROR.
• Une clé API expirée donne 401 ACCESS_DENIED, comme une clé inconnue.
• Il existe une constante Code* pour chaque code documenté par l’API. L’API envoie désormais 429 RATE_LIMITED (CodeRateLimited) là où elle envoyait RATE_LIMIT et RATE_LIMIT_EXCEEDED ; CodeRateLimit et CodeRateLimitExceeded restent, dépréciées.
• Chaque erreur de AI.Chat a la forme OpenAI avec un code en minuscules (access_denied, rate_limit_exceeded, server_overloaded, …), que Code reprend tel quel.
• Error() produit squarecloud: <METHOD> <path>: HTTP <status> <CODE>: <message> (v2 : squarecloud: <message> (<CODE>, HTTP <status>)). Basez-vous sur les champs, pas sur le texte.

​

Changements de comportement

• Clé API vide : New("") (ou une clé composée uniquement d’espaces) renvoie toujours un client (il ne peut pas renvoyer d’erreur), mais chaque appel sauf Service.Status échoue localement avec INVALID_API_KEY.
• Snapshot 202 : la v2 renvoyait une *APIError avec StatusCode 202. La v3 renvoie un SnapshotCreated avec Pending: true et une erreur nil.
• Temps réel : Next renvoie désormais un RealtimeEvent. Faites un switch sur ev.Event (system, status, logs, error, message). Pour les logs, affichez ev.Line (l’octet \u0001/\u0002 est retiré ; ev.Data reste la trame brute) et utilisez ev.Stream pour stdout/stderr. Pour le statut, utilisez ev.Status : jamais nil sur un événement de statut, fusionné superficiellement entre les trames et les reconnexions. Après REALTIME_DISCONNECTED, Next renvoie io.EOF. Le flux ne s’arrête plus au bout de 30 s, les reconnexions attendent au moins 5,5 s après l’ouverture précédente, et l’ouverture est bornée par le timeout du client jusqu’à l’arrivée des en-têtes. Voir Temps réel.
• Timeouts : la v2 utilisait un timeout fixe de 30 s du http.Client pour tout. La v3 n’applique une échéance par défaut que lorsque ctx n’en a pas : le timeout du client (WithTimeout, 30 s) pour la plupart des appels ; au moins 2 minutes pour start/stop/restart, la création de base de données, la création et la restauration de snapshot et AI.Chat ; aucune pour les envois, les écritures de fichiers de plus de 1 MiB de contenu et les téléchargements de snapshots. WithTimeout(0) les désactive toutes.
• Fenêtres réseau vides : Analytics, Errors et Performance renvoient des pointeurs nil lorsque la fenêtre n’a pas de trafic.
• En-têtes : chaque requête à l’API envoie Accept: application/json (text/event-stream pour le temps réel). Le User-Agent par défaut est passé de Square GO à squarecloud-sdk-go/3.0.0 (WithUserAgent le remplace toujours).
• Identifiants : chaque identifiant est désormais encodé en pourcentage comme un seul segment de chemin (la v2 le collait tel quel dans le chemin), et un identifiant vide, . ou .. échoue localement avec INVALID_ID.
• Écriture de fichiers : la v2 envoyait toujours le contenu sous forme de chaîne, ce qui corrompait les fichiers binaires, et ne pouvait pas écrire de fichier vide. La v3 envoie toujours le contenu encodé en base64 : chaque octet est donc conservé, un contenu vide écrit un fichier vide, et un contenu de plus de 10 Mo échoue localement avec FILE_TOO_LARGE. L’API répond 400 INVALID_CONTENT pour un contenu qu’elle ne peut pas décoder.
• Lecture de fichiers : la v3 demande toujours du base64 et le décode, au lieu du tableau d’octets JSON que lisait la v2 (déprécié par l’API). Un fichier de plus de 10 Mo donne 413 FILE_TOO_LARGE.
• Liste de fichiers : lister un répertoire inexistant donne 404 FILE_NOT_FOUND ; c’était auparavant une liste vide.
• Snapshots : les entrées de la liste portent VersionID et URL fournis par l’API ; rien n’est extrait de Key.
• Nouvelles tentatives : nouveau. Les erreurs réseau sur GET, les 503 UPLOAD_BUSY/ANALYTICS_BUSY et le 503 DATABASE_UNAVAILABLE sur GET sont réessayés deux fois par défaut ; WithMaxRetries(0) rétablit le comportement de la v2. DATABASE_UNAVAILABLE peut arriver après le début d’une mutation : le SDK ne le réessaie donc jamais sur les autres méthodes ; réessayez vous-même une mutation idempotente si vous le souhaitez. Voir Nouvelles tentatives.
• Version de Go : le minimum est passé de Go 1.24 à Go 1.22.