std.cloud.gcp

Google Cloud Platform Bindings — 11 Units für Cloud Storage (GCS), Compute Engine (GCE), Cloud Firestore, Pub/Sub, Cloud Functions, Cloud Run, Cloud Logging, Cloud Monitoring, Secret Manager und IAM. Vollständig in Lyx implementiert, kein GCP SDK. Alle HTTPS-Anfragen laufen über std.net.tls; Authentifizierung über JWT RS256 (Service Accounts), OAuth 2.0 Refresh Token oder GCE-Metadata-Server.

→ Standard Library · std.cloud · std.crypto

┌───────────────────────────────────────────────────────────────────┐
│  Service-Units                                                     │
│  storage (GCS) · compute (GCE) · firestore · pubsub              │
│  functions (GCF + GCR) · logging (+ Monitoring) · secrets (+ IAM)│
├───────────────────────────────────────────────────────────────────┤
│  Interne GCP-Schichten                                             │
│  gcp/credentials  (Credential Chain, Token-Cache)                 │
│  gcp/jwt          (JWT RS256, GCPServiceAccount)                  │
│  gcp/oauth        (GCPToken, auto-Refresh)                        │
│  gcp/transport    (GCPClient, GCPResponse, Retry, Backoff)        │
├───────────────────────────────────────────────────────────────────┤
│  Netzwerk-Grundschicht                                             │
│  std.net.tls · std.net.http                                       │
└───────────────────────────────────────────────────────────────────┘

GCPCredentialsDefault durchsucht drei Quellen in dieser Reihenfolge:

1. GOOGLE_APPLICATION_CREDENTIALS — Umgebungsvariable zeigt auf eine JSON-Datei (Service Account oder Authorized User)
2. ADC-Datei — ~/.config/gcloud/application_default_credentials.json (nach gcloud auth application-default login)
3. GCE-Metadata-Server — automatisch auf Google Compute Engine (metadata.google.internal)

Der Token wird im GCPCredentials-Struct gecacht und automatisch erneuert, sobald er weniger als 60 Sekunden gültig ist.

import std.cloud.gcp.credentials;
import std.cloud.gcp.storage;

fn main(): int64 {
    // Credential Chain: env → ADC → GCE-Metadata
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/cloud-platform"c);

    var gcs: GCSConn := GCSConnect(addr creds, "mein-projekt"c);

    var data: pchar := "Hello GCS"c;
    GCSUpload(gcs, "mein-bucket"c, "hello.txt"c, data as int64, 9, "text/plain"c);

    GCSDisconnect(gcs);
    GCPCredentialsFree(creds);
    return 0;
}

Alle Service-Funktionen geben GCPResponse zurück:

GCPResponseFree® gibt body und contentType frei.

Der Transport-Layer wiederholt Anfragen bei 429, 500, 502, 503 und 504 automatisch — bis zu 3 Mal, mit exponentiellem Backoff (100 ms × 2ⁿ). User-Agent: lyxgcloud/1.0.

API: storage.googleapis.com · Pfad: /storage/v1/b/{bucket}/o/{object}

import std.cloud.gcp.credentials;
import std.cloud.gcp.storage;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/devstorage.read_write"c);
    var gcs: GCSConn := GCSConnect(addr creds, "mein-projekt"c);

    // Datei hochladen
    var data: pchar := "Hallo Welt"c;
    GCSUpload(gcs, "mein-bucket"c, "test.txt"c, data as int64, 10, "text/plain"c);

    // Datei herunterladen
    var r: GCPResponse := GCSDownload(gcs, "mein-bucket"c, "test.txt"c);
    if (r.statusCode == 200) {
        Print(r.body as pchar); PrintLn(""c);
    }
    GCPResponseFree(r);

    GCSDisconnect(gcs);
    GCPCredentialsFree(creds);
    return 0;
}

API: compute.googleapis.com · Standard-Zone: europe-west1-b

Asynchrone Operationen (Erstellen, Löschen, Starten, Stoppen) geben GCEOperation zurück. GCEOperationWait pollt alle 2 Sekunden, maximal 30 Versuche (60 Sekunden gesamt).

import std.cloud.gcp.credentials;
import std.cloud.gcp.compute;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/compute"c);
    var gce: GCEConn := GCEConnect(addr creds, "mein-projekt"c, "europe-west1-b"c);

    var op: GCEOperation := GCEInstanceCreate(gce, "web-01"c, "e2-micro"c,
        "projects/debian-cloud/global/images/debian-12-bookworm-v20250101"c, 20);
    op = GCEOperationWait(gce, op);
    if (op.done == 1) {
        PrintLn("VM bereit"c);
    }
    GCEOperationFree(op);

    GCEDisconnect(gce);
    GCPCredentialsFree(creds);
    return 0;
}

API: firestore.googleapis.com · Standard-Datenbank: (default)

Dokumente werden über FSDoc verwaltet (max. 64 Felder). Unterstützte Feldtypen: String, Int64, Bool, Null.

Hinweis zu FSGet: Das zurückgegebene FSDoc enthält das Feld „json“ mit dem Roh-JSON-Body der Firestore REST-Antwort. Ein vollständiger Firestore-Value-Type-Parser (stringValue, integerValue …) ist nicht implementiert — bei Bedarf muss der JSON-Body selbst ausgewertet werden.

import std.cloud.gcp.credentials;
import std.cloud.gcp.firestore;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/datastore"c);
    var fs: FirestoreConn := FirestoreConnect(addr creds, "mein-projekt"c, "(default)"c);

    var doc: int64 := FSDocNew();
    FSDocSetString(doc, "name"c, "Andreas"c);
    FSDocSetInt(doc, "version"c, 1);
    FSDocSetBool(doc, "aktiv"c, 1);
    FSCreate(fs, "users"c, "user-1"c, doc);
    FSDocFree(doc);

    FirestoreDisconnect(fs);
    GCPCredentialsFree(creds);
    return 0;
}

API: pubsub.googleapis.com · Ressourcen-Format: projects/{project}/topics/{topic}

Nachrichten-Payload wird beim Publishen automatisch als Base64url kodiert. PubSubAck erwartet ein int64*-Array von pchar-Zeigern (die ackId-Strings aus der Pull-Antwort).

import std.cloud.gcp.credentials;
import std.cloud.gcp.pubsub;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/pubsub"c);
    var ps: PubSubConn := PubSubConnect(addr creds, "mein-projekt"c);

    PubSubTopicCreate(ps, "events"c);
    PubSubSubscriptionCreate(ps, "events-sub"c, "events"c, 60);

    var msg: pchar := "Ereignis eingetreten"c;
    var r: GCPResponse := PubSubPublish(ps, "events"c, msg as int64, 20);
    GCPResponseFree(r);

    PubSubDisconnect(ps);
    GCPCredentialsFree(creds);
    return 0;
}

Beide Dienste nutzen dieselbe Region-Konfiguration. Standard-Region: europe-west1.

Cloud Functions v2: API cloudfunctions.googleapis.com · Pfad /v2/projects/{proj}/locations/{region}/functions

Cloud Run v2: API run.googleapis.com · Pfad /v2/projects/{proj}/locations/{region}/services

Hinweis: GCRServiceInvoke ist ein Platzhalter (gibt HTTP 501 zurück). Cloud Run Services werden über ihre eigene Service-URL aufgerufen — dafür direkt std.net.https mit Bearer-Token aus GCPGetToken verwenden.

import std.cloud.gcp.credentials;
import std.cloud.gcp.functions;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/cloud-platform"c);
    var gcf: GCFConn := GCFConnect(addr creds, "mein-projekt"c, "europe-west1"c);

    // Cloud Function deployen (Quellcode als ZIP in GCS)
    var r: GCPResponse := GCFDeploy(gcf, "helloWorld"c, "nodejs20"c,
                                    "helloWorld"c, "mein-bucket/function.zip"c);
    GCPResponseFree(r);

    // Function aufrufen
    var body: pchar := "{\"name\":\"Lyx\"}"c;
    var res: GCPResponse := GCFInvoke(gcf, "helloWorld"c, body as int64, 14);
    if (res.statusCode == 200) {
        Print(res.body as pchar); PrintLn(""c);
    }
    GCPResponseFree(res);

    GCFDisconnect(gcf);
    GCPCredentialsFree(creds);
    return 0;
}

Logging: API logging.googleapis.com · Endpunkt POST /v2/entries:write

Log-Einträge werden mit resource.type=„global“ erstellt. Der vollständige Log-Name wird automatisch aus projects/{project}/logs/{logName} zusammengebaut.

Monitoring: API monitoring.googleapis.com · Endpunkt POST /v3/projects/{project}/timeSeries

MonWriteMetric schreibt einen Integer-Gauge-Wert als Custom Metric Time Series. metricType muss mit custom.googleapis.com/ beginnen.

import std.cloud.gcp.credentials;
import std.cloud.gcp.logging;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/logging.write"c);
    var log: LogConn := LogConnect(addr creds, "mein-projekt"c);

    LogWrite(log, "app-log"c, LOG_INFO, "Anwendung gestartet"c);

    var json: pchar := "{\"event\":\"startup\",\"version\":2}"c;
    LogWriteJSON(log, "app-log"c, LOG_INFO, json as int64, 30);

    var mon: MonConn := MonConnect(addr creds, "mein-projekt"c);
    MonWriteMetric(mon, "custom.googleapis.com/anfragen_pro_sekunde"c, 42, 0);

    MonDisconnect(mon);
    LogDisconnect(log);
    GCPCredentialsFree(creds);
    return 0;
}

Secret Manager: API secretmanager.googleapis.com · Pfad /v1/projects/{project}/secrets

Secrets werden base64url-kodiert gespeichert. SecretCreate führt zwei API-Aufrufe durch: Zuerst wird das Secret angelegt (automatische Replikation), dann wird die erste Version mit dem Payload hinzugefügt.

SecretGetLatest und SecretGet dekodieren den Payload automatisch und geben einen allokierten pchar zurück (Caller frees mit free(val, StrLen(val) + 1)).

IAM: API iam.googleapis.com · Pfad /v1/projects/{project}/serviceAccounts

import std.cloud.gcp.credentials;
import std.cloud.gcp.secrets;
import std.alloc;

fn main(): int64 {
    var creds: GCPCredentials := GCPCredentialsDefault(
        "https://www.googleapis.com/auth/cloud-platform"c);
    var sc: SecretConn := SecretConnect(addr creds, "mein-projekt"c);

    // Secret anlegen (Payload wird base64url-kodiert gespeichert)
    var payload: pchar := "geheimes-passwort-123"c;
    SecretCreate(sc, "db-password"c, payload as int64, 21);

    // Secret auslesen (automatisch dekodiert)
    var val: int64 := SecretGet(sc, "db-password"c);
    if (val != 0) {
        Print(val as pchar); PrintLn(""c);
        free(val, StrLen(val as pchar) + 1);
    }

    SecretDisconnect(sc);
    GCPCredentialsFree(creds);
    return 0;
}

Letzte Aktualisierung: 2026-06-13