Tag 7: HTTP-Client, context, Timeouts, Retries – ghrel
Ziel: Ein CLI, das GitHub-Releases abfragt – mit Timeout pro Versuch, Gesamtbudget per context und Retries mit Backoff · Dauer: ca. 120 min · Voraussetzung: Tag 6
Briefing
net/httpreicht: Request bauen, Header setzen, JSON in Structs dekodieren.- Zwei Zeitgrenzen:
http.Client.Timeoutpro Versuch,context.WithTimeoutfür alles inklusive Retries. - Retry nur, wenn es Sinn hat: 429, 5xx, Netzfehler – nie bei 404 oder abgelaufenem Context.
Retry-Aftervom Server schlägt das eigene Backoff.- Tests laufen gegen
httptest.Server– kein Netz, kein Rate-Limit, deterministisch.
ghrel ---ctx (15 s gesamt)---------------------------------------------.
Versuch 1 (max 5 s) -> 503 | warte 0,5 s | Versuch 2 -> 503 | warte 1 s |
Versuch 3 -> 200 -> JSON -> Tabelle |
'-------------------------------------- ctx abgelaufen? -> sofort Abbruch'
Drill 1: Modul ohne Abhängigkeiten
mkdir -p ~/go-lab/tag07-ghrel && cd ~/go-lab/tag07-ghrel
go mod init example.com/ghrel
mkdir -p cmd/ghrel internal/github
curl -s https://api.github.com/repos/openbao/openbao/releases/latest \
| jq '{tag_name, name, prerelease, published_at}'Erwartet (gekürzt, Werte ändern sich mit jedem Release):
go: creating new go.mod: module example.com/ghrel
{
"tag_name": "v2.7.1",
"name": "v2.7.1",
"prerelease": false,
"published_at": "2026-10-01T14:03:19Z"
}
Warum curl zuerst? So siehst du die echte Form des JSON, bevor du Structs dafür schreibst. Ohne Token erlaubt GitHub 60 Anfragen pro Stunde und IP – für heute genug.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Typen und Client
JSON-Tags verbinden tag_name mit TagName;
time.Time versteht RFC 3339 direkt. Felder, die du nicht
deklarierst, ignoriert encoding/json.
cat > internal/github/client.go <<'EOF'
// Package github ist ein minimaler Client für die GitHub-Releases-API.
package github
import (
"context"
"fmt"
"net/http"
"time"
)
// Release enthält die Felder, die ghrel anzeigt.
type Release struct {
TagName string `json:"tag_name"`
Name string `json:"name"`
Prerelease bool `json:"prerelease"`
PublishedAt time.Time `json:"published_at"`
HTMLURL string `json:"html_url"`
}
// APIError ist eine Antwort mit Status >= 400.
type APIError struct {
Status int
Message string
}
func (e *APIError) Error() string {
return fmt.Sprintf("GitHub-API: %d %s", e.Status, e.Message)
}
// Client spricht mit api.github.com (oder einem Testserver).
type Client struct {
BaseURL string // z. B. https://api.github.com
Token string // optional; erhöht das Rate-Limit von 60 auf 5000/h
HTTP *http.Client // mit Timeout pro Versuch
Retries int // zusätzliche Versuche bei 429/5xx/Netzfehlern
Backoff time.Duration // Wartezeit vor dem 1. Retry, danach verdoppelt
}
// Releases liefert die neuesten n Releases von owner/repo.
func (c *Client) Releases(ctx context.Context, repo string, n int) ([]Release, error) {
var rs []Release
err := c.get(ctx, fmt.Sprintf("/repos/%s/releases?per_page=%d", repo, n), &rs)
return rs, err
}
// Latest liefert das neueste stabile Release (keine Drafts/Prereleases).
func (c *Client) Latest(ctx context.Context, repo string) (Release, error) {
var r Release
err := c.get(ctx, "/repos/"+repo+"/releases/latest", &r)
return r, err
}
EOFWarum ein eigener Fehlertyp? Der Aufrufer will mit
errors.As (Tag 3) an den Status kommen, um 404 freundlich
zu melden – ein String-Vergleich auf die Fehlermeldung wäre
zerbrechlich.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Ein Versuch, dann Retries
cat > internal/github/retry.go <<'EOF'
package github
import (
"context"
"encoding/json"
"errors"
"fmt"
"io"
"net/http"
"strconv"
"time"
)
// get holt path und dekodiert JSON nach v – mit Retries und Backoff.
func (c *Client) get(ctx context.Context, path string, v any) error {
wait := c.Backoff
for attempt := 0; ; attempt++ {
retryAfter, err := c.do(ctx, path, v)
if err == nil || attempt >= c.Retries || ctx.Err() != nil || !retryable(err) {
return err
}
if retryAfter > 0 {
wait = retryAfter // Server-Vorgabe schlägt eigene Schätzung
}
select {
case <-ctx.Done(): // Gesamtbudget aufgebraucht oder Strg+C
return fmt.Errorf("%w (letzter Fehler: %v)", ctx.Err(), err)
case <-time.After(wait):
}
wait *= 2
}
}
// do macht genau einen Versuch.
func (c *Client) do(ctx context.Context, path string, v any) (time.Duration, error) {
req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.BaseURL+path, nil)
if err != nil {
return 0, err
}
req.Header.Set("Accept", "application/vnd.github+json")
req.Header.Set("X-GitHub-Api-Version", "2022-11-28")
req.Header.Set("User-Agent", "ghrel-lab") // ohne User-Agent lehnt GitHub ab
if c.Token != "" {
req.Header.Set("Authorization", "Bearer "+c.Token)
}
resp, err := c.HTTP.Do(req)
if err != nil {
return 0, err
}
defer resp.Body.Close()
if resp.StatusCode >= 400 {
var body struct{ Message string }
_ = json.NewDecoder(io.LimitReader(resp.Body, 64<<10)).Decode(&body)
secs, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
return time.Duration(secs) * time.Second,
&APIError{Status: resp.StatusCode, Message: body.Message}
}
return 0, json.NewDecoder(resp.Body).Decode(v)
}
// retryable: 429, 5xx und Netzfehler ja, übrige 4xx nein.
func retryable(err error) bool {
var ae *APIError
if errors.As(err, &ae) {
return ae.Status == http.StatusTooManyRequests || ae.Status >= 500
}
return true // Netzfehler: Verbindung abgelehnt, Reset, Timeout pro Versuch
}
EOFWarum? NewRequestWithContext bindet den Request an den
Context: Läuft das Budget ab, bricht auch eine hängende Verbindung
sofort ab. Das select wartet auf das Backoff
oder das Ende des Contexts – ein nacktes
time.Sleep würde Strg+C ignorieren.
io.LimitReader schützt davor, dass eine riesige Fehlerseite
den Speicher füllt.
Tipp: Retries sind nur für idempotente Anfragen sicher. GET darf man wiederholen, ein POST, das eine Bestellung anlegt, nicht ohne Idempotency-Key.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Das CLI
run bekommt Context, Argumente, Umgebung und Writer –
wie an Tag 6. GHREL_API biegt die Basis-URL um (Tests,
GitHub Enterprise), cmp.Or nimmt den ersten nicht-leeren
Wert.
cat > cmd/ghrel/main.go <<'EOF'
// ghrel zeigt GitHub-Releases eines Repos: ghrel [-n 5] [-latest] owner/repo
package main
import (
"cmp"
"context"
"encoding/json"
"errors"
"flag"
"fmt"
"io"
"net/http"
"os"
"os/signal"
"strings"
"text/tabwriter"
"time"
"example.com/ghrel/internal/github"
)
func main() {
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
os.Exit(run(ctx, os.Args[1:], os.Getenv, os.Stdout, os.Stderr))
}
func run(ctx context.Context, args []string, getenv func(string) string,
stdout, stderr io.Writer) int {
fl := flag.NewFlagSet("ghrel", flag.ContinueOnError)
fl.SetOutput(stderr)
n := fl.Int("n", 5, "Anzahl Releases")
latest := fl.Bool("latest", false, "nur das neueste stabile Release")
asJSON := fl.Bool("json", false, "JSON statt Tabelle")
timeout := fl.Duration("timeout", 15*time.Second, "Gesamtbudget inkl. Retries")
if err := fl.Parse(args); err != nil {
return 2
}
repo := fl.Arg(0)
if fl.NArg() != 1 || strings.Count(repo, "/") != 1 {
fmt.Fprintln(stderr, "Aufruf: ghrel [-n 5] [-latest] [-json] owner/repo")
return 2
}
c := &github.Client{
BaseURL: cmp.Or(getenv("GHREL_API"), "https://api.github.com"),
Token: getenv("GITHUB_TOKEN"),
HTTP: &http.Client{Timeout: 5 * time.Second}, // pro Versuch
Retries: 3,
Backoff: 500 * time.Millisecond,
}
ctx, cancel := context.WithTimeout(ctx, *timeout)
defer cancel()
var rs []github.Release
var err error
if *latest {
var r github.Release
r, err = c.Latest(ctx, repo)
rs = []github.Release{r}
} else {
rs, err = c.Releases(ctx, repo, *n)
}
var ae *github.APIError
switch {
case errors.As(err, &ae) && ae.Status == http.StatusNotFound:
fmt.Fprintf(stderr, "ghrel: %s nicht gefunden (oder keine Releases)\n", repo)
return 1
case err != nil:
fmt.Fprintln(stderr, "ghrel:", err)
return 1
}
if *asJSON {
enc := json.NewEncoder(stdout)
enc.SetIndent("", " ")
_ = enc.Encode(rs)
return 0
}
tw := tabwriter.NewWriter(stdout, 0, 4, 2, ' ', 0)
fmt.Fprintln(tw, "TAG\tDATUM\tNAME")
for _, r := range rs {
name := r.Name
if r.Prerelease {
name += " (pre)"
}
date := r.PublishedAt.Format(time.DateOnly)
fmt.Fprintf(tw, "%s\t%s\t%s\n", r.TagName, date, name)
}
_ = tw.Flush()
return 0
}
EOFgo vet ./... && go build -o ghrel ./cmd/ghrel
./ghrel -n 3 kubernetes/kubernetes
./ghrel -latest openbao/openbao
./ghrel nobody-xyz/nope-123; echo "Exit: $?"Erwartet (gekürzt, Werte ändern sich):
TAG DATUM NAME
v1.38.0-alpha.2 2026-10-07 v1.38.0-alpha.2 (pre)
v1.38.0-alpha.1 2026-09-29 v1.38.0-alpha.1 (pre)
v1.37.1 2026-09-23 v1.37.1
TAG DATUM NAME
v2.7.1 2026-10-01 v2.7.1
ghrel: nobody-xyz/nope-123 nicht gefunden (oder keine Releases)
Exit: 1
Warum time.DateOnly? Go formatiert Zeiten mit dem
Referenzdatum 2006-01-02 15:04:05; die Konstante erspart
dir das Auswendiglernen.
Sicherheit: Mit mehr Kontingent:
GITHUB_TOKEN=$(gh auth token) ./ghrel …– der Token kommt nur aus der Umgebung, nie in Code, Flags oder Shell-History.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Retries live sehen
Port 9 (discard) ist auf dem Mac geschlossen – jede Verbindung wird sofort abgelehnt, also ein Netzfehler, also Retry.
time GHREL_API=http://127.0.0.1:9 ./ghrel acme/tool
time GHREL_API=http://127.0.0.1:9 ./ghrel -timeout 1s acme/toolErwartet (gekürzt):
ghrel: Get "http://127.0.0.1:9/repos/acme/tool/releases?per_page=5": dial tcp …
… 3,591 total
ghrel: context deadline exceeded (letzter Fehler: Get "http://127.0.0.1:9/repos…
… 1,014 total
Warum 3,6 s? Ein Versuch plus drei Retries mit 0,5 + 1 + 2 s Backoff.
Mit -timeout 1s greift das Gesamtbudget mitten im Warten –
und der Fehler nennt beides: Abbruchgrund und letzte Ursache.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Tests gegen httptest
httptest.NewServer startet einen echten HTTP-Server auf
einem freien Port. Der Handler spielt GitHub – inklusive Fehlern, die du
beim echten GitHub nie gezielt auslösen könntest.
cat > internal/github/client_test.go <<'EOF'
package github
import (
"context"
"errors"
"fmt"
"net/http"
"net/http/httptest"
"sync/atomic"
"testing"
"time"
)
// newTestClient startet einen Fake-GitHub; winziger Backoff hält Tests schnell.
func newTestClient(t *testing.T, h http.HandlerFunc) *Client {
t.Helper()
srv := httptest.NewServer(h)
t.Cleanup(srv.Close)
return &Client{BaseURL: srv.URL, Token: "lab-token", HTTP: srv.Client(),
Retries: 3, Backoff: time.Millisecond}
}
func TestReleasesHeaderUndJSON(t *testing.T) {
c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
if r.URL.Path != "/repos/acme/tool/releases" ||
r.URL.Query().Get("per_page") != "2" {
t.Errorf("falsche URL: %s", r.URL)
}
if got := r.Header.Get("Authorization"); got != "Bearer lab-token" {
t.Errorf("Authorization = %q", got)
}
fmt.Fprint(w, `[{"tag_name":"v1.2.0","prerelease":false,
"published_at":"2026-10-01T12:00:00Z"},{"tag_name":"v1.1.0"}]`)
})
rs, err := c.Releases(context.Background(), "acme/tool", 2)
if err != nil {
t.Fatal(err)
}
if len(rs) != 2 || rs[0].TagName != "v1.2.0" || rs[0].PublishedAt.Day() != 1 {
t.Errorf("Releases = %+v", rs)
}
}
func TestRetry(t *testing.T) {
tests := []struct {
name string
failWith int // Status der ersten beiden Antworten
wantCalls int32
wantErr bool
}{
{"503 wird wiederholt", http.StatusServiceUnavailable, 3, false},
{"429 wird wiederholt", http.StatusTooManyRequests, 3, false},
{"404 sofort Fehler", http.StatusNotFound, 1, true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
var calls atomic.Int32 // Handler laufen in eigenen Goroutines
c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
if calls.Add(1) <= 2 {
w.Header().Set("Retry-After", "0")
http.Error(w, `{"message":"kaputt"}`, tt.failWith)
return
}
fmt.Fprint(w, `{"tag_name":"v1.0.0"}`)
})
_, err := c.Latest(context.Background(), "acme/tool")
if (err != nil) != tt.wantErr || calls.Load() != tt.wantCalls {
t.Errorf("err=%v calls=%d, want err=%v calls=%d",
err, calls.Load(), tt.wantErr, tt.wantCalls)
}
})
}
}
func TestAPIErrorPerErrorsAs(t *testing.T) {
c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
w.WriteHeader(http.StatusNotFound)
fmt.Fprint(w, `{"message":"Not Found"}`)
})
_, err := c.Latest(context.Background(), "acme/fehlt")
var ae *APIError
if !errors.As(err, &ae) || ae.Status != 404 || ae.Message != "Not Found" {
t.Errorf("err = %v", err)
}
}
func TestGesamtTimeout(t *testing.T) {
c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
select { // hängt, bis der Client aufgibt
case <-r.Context().Done():
case <-time.After(2 * time.Second):
}
})
ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
defer cancel()
start := time.Now()
_, err := c.Latest(ctx, "acme/tool")
if !errors.Is(err, context.DeadlineExceeded) {
t.Errorf("err = %v, want DeadlineExceeded", err)
}
if d := time.Since(start); d > time.Second {
t.Errorf("hat %v gedauert – Context ignoriert?", d)
}
}
EOFgo test -race -count=1 -v ./internal/github 2>&1 | grep -E '^(---|ok|\s+---)'Erwartet:
--- PASS: TestReleasesHeaderUndJSON (0.00s)
--- PASS: TestRetry (0.01s)
--- PASS: TestRetry/503_wird_wiederholt (0.00s)
--- PASS: TestRetry/429_wird_wiederholt (0.00s)
--- PASS: TestRetry/404_sofort_Fehler (0.00s)
--- PASS: TestAPIErrorPerErrorsAs (0.00s)
--- PASS: TestGesamtTimeout (0.05s)
ok example.com/ghrel/internal/github 1.250s
Warum atomic.Int32? Der Handler läuft in einer anderen
Goroutine als der Test. Ein normales int wäre ein Data Race
– -race würde es melden (mehr dazu an Tag 8).
Fortschritt speichern? Kostenlos registrieren
Drill 7: Das CLI testen
Über GHREL_API zeigt run auf den
Testserver. Die Tabelle prüfst du byte-genau – tabwriter
richtet nach der längsten Zelle aus.
cat > cmd/ghrel/main_test.go <<'EOF'
package main
import (
"bytes"
"context"
"fmt"
"net/http"
"net/http/httptest"
"testing"
)
func TestRunTabelle(t *testing.T) {
h := func(w http.ResponseWriter, r *http.Request) {
fmt.Fprint(w, `[{"tag_name":"v2.0.0-rc.1","name":"RC","prerelease":true,
"published_at":"2026-10-02T08:00:00Z"}]`)
}
srv := httptest.NewServer(http.HandlerFunc(h))
defer srv.Close()
env := map[string]string{"GHREL_API": srv.URL}
var out bytes.Buffer
code := run(context.Background(), []string{"acme/tool"},
func(k string) string { return env[k] }, &out, &out)
want := "TAG DATUM NAME\nv2.0.0-rc.1 2026-10-02 RC (pre)\n"
if code != 0 || out.String() != want {
t.Errorf("Exit %d, Ausgabe:\n%s\nwant:\n%s", code, out.String(), want)
}
}
func TestRunFalscherAufruf(t *testing.T) {
var out bytes.Buffer
getenv := func(string) string { return "" }
code := run(context.Background(), []string{"nurname"}, getenv, &out, &out)
if code != 2 {
t.Errorf("Exit %d, want 2", code)
}
}
EOFgo test -race -count=1 ./...Erwartet:
ok example.com/ghrel/cmd/ghrel 1.177s
ok example.com/ghrel/internal/github 1.365s
Fortschritt speichern? Kostenlos registrieren
Drill 8: Das Tool ist fertig
cp ../tag06-manifestlint/.golangci.yml .
gofmt -l . && go vet ./... && ~/go-lab/bin/lint run ./...
go build -o ghrel ./cmd/ghrel
./ghrel -n 2 -json cli/cli | jq -r '.[] | "\(.tag_name) \(.html_url)"'
./ghrel; echo "Exit: $?"Erwartet (gekürzt, Werte ändern sich):
0 issues.
v2.102.0 https://github.com/cli/cli/releases/tag/v2.102.0
v2.101.0 https://github.com/cli/cli/releases/tag/v2.101.0
Aufruf: ghrel [-n 5] [-latest] [-json] owner/repo
Exit: 2
ghrel ist jetzt ein Baustein für Skripte: „Gibt es eine
neuere OpenBao-Version als die im Cluster?” ist ein Einzeiler mit
-latest -json | jq -r '.[0].tag_name'.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
cd ~/go-lab/tag07-ghrel
ok() { echo "✔ $1"; }; nok() { echo "✘ $1"; }
go vet ./... && go test -race -count=1 ./... >/dev/null && ok "vet + Tests (race)" \
|| nok "Tests"
./ghrel -latest openbao/openbao | grep -q '^v2\.' && ok "echtes GitHub" || nok "API"
./ghrel nobody-xyz/nope-123 2>/dev/null; [ $? -eq 1 ] && ok "404 -> Exit 1" \
|| nok "404"
s=$(date +%s); GHREL_API=http://127.0.0.1:9 ./ghrel -timeout 1s a/b 2>/dev/null
[ $(( $(date +%s) - s )) -le 2 ] && ok "Gesamtbudget greift" || nok "Timeout"Erwartet:
✔ vet + Tests (race)
✔ echtes GitHub
✔ 404 -> Exit 1
✔ Gesamtbudget greift
Challenge
Ist das Kontingent ohne Token erschöpft, antwortet GitHub mit
403, X-RateLimit-Remaining: 0 und der
Reset-Zeit als Unix-Sekunden in X-RateLimit-Reset.
Erweitere APIError, sodass die Fehlermeldung die Uhrzeit
nennt, ab der es wieder geht – und schreibe einen Test dafür.
Hinweis: time.Unix(sek, 0) macht aus
Unix-Sekunden ein time.Time; ein Retry wäre hier falsch,
denn der Reset liegt oft Minuten entfernt.
Lösung
In client.go APIError und
Error() ersetzen:
type APIError struct {
Status int
Message string
Reset time.Time // gesetzt, wenn das Rate-Limit erschöpft ist
}
func (e *APIError) Error() string {
msg := fmt.Sprintf("GitHub-API: %d %s", e.Status, e.Message)
if !e.Reset.IsZero() {
msg += fmt.Sprintf(" (Limit wieder frei um %s)", e.Reset.Format(time.TimeOnly))
}
return msg
}
In retry.go die letzten drei Zeilen des Fehlerzweigs in
do ersetzen:
ae := &APIError{Status: resp.StatusCode, Message: body.Message}
if resp.Header.Get("X-RateLimit-Remaining") == "0" {
reset, _ := strconv.ParseInt(resp.Header.Get("X-RateLimit-Reset"), 10, 64)
ae.Reset = time.Unix(reset, 0)
}
secs, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
return time.Duration(secs) * time.Second, ae
cat >> internal/github/client_test.go <<'EOF'
func TestRateLimit(t *testing.T) {
c := newTestClient(t, func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("X-RateLimit-Remaining", "0")
w.Header().Set("X-RateLimit-Reset", "1791640800")
w.WriteHeader(http.StatusForbidden)
fmt.Fprint(w, `{"message":"API rate limit exceeded"}`)
})
_, err := c.Latest(context.Background(), "acme/tool")
var ae *APIError
if !errors.As(err, &ae) || ae.Reset.Unix() != 1791640800 {
t.Fatalf("err = %v", err)
}
t.Log(err)
}
EOF
go test -count=1 -v -run RateLimit ./internal/github | grep -v '^=== 'Erwartet (Uhrzeit hängt von deiner Zeitzone ab):
client_test.go:118: GitHub-API: 403 API rate limit exceeded (Limit wieder frei…
--- PASS: TestRateLimit (0.01s)
PASS
ok example.com/ghrel/internal/github 0.242s
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Hinter Firmen-Proxies:
http.DefaultTransportliestHTTPS_PROXY/NO_PROXYautomatisch; eigene CAs kommen über den System-Trust-Store odertls.Config.RootCAs. - GitHub Enterprise Server hat die API unter
https://<host>/api/v3– genau dafür gibt esGHREL_API. - Für Automatisierung statt persönlicher Tokens eine GitHub App oder
fein granulierte Tokens mit nur
contents:read; Tokens aus Vault/OpenBao statt aus.env-Dateien. - Viele Clients gleichzeitig: Jitter zum Backoff addieren, sonst kommen alle Retries im selben Takt zurück (Thundering Herd).
- Retries, Status-Codes und Dauer gehören in Metriken und Logs (Tag 9) – stille Retries verstecken Störungen beim Anbieter.