01Open Source · API Client

spacetraders-client

Ein veröffentlichter Rust-Client mit generierten OpenAPI-Typen, einer ergonomischen API und einem prioritätsgesteuerten Request-Scheduler für verlässliche Kommunikation unter engen Rate Limits.

Zeitraum
2026
Status
Veröffentlicht
Meine Rolle
End-to-End-Entwicklung und Veröffentlichung

01 — Ausgangslage

Problem & Kontext

SpaceTraders ist ein programmierbares Online-Spiel mit einer HTTP-API. Automatisierte Clients koordinieren darüber unter anderem Navigation, Handel und Flottenaktionen. Die API begrenzt die Anzahl der Anfragen eng, sodass ein Client nicht nur korrekte Datentypen, sondern auch kontrollierte Nebenläufigkeit benötigt.

Das Projekt entstand als eigenständiges Open-Source-Paket. Ziel war eine belastbare Grundlage für weitere Rust-Anwendungen, ohne die Komplexität von Scheduling, Fehlerklassifikation und Spezifikationsänderungen in jedem Verbraucher erneut lösen zu müssen.

Professionelle Rahmenbedingungen

  • Enge API-Rate-Limits müssen auch bei mehreren gleichzeitigen Aufgaben eingehalten werden.
  • Kritische Aktionen sollen bevorzugt werden, ohne normale oder niedrig priorisierte Arbeit dauerhaft zu verdrängen.
  • Wiederholungen sind bei lesenden Anfragen meist sicher, bei nicht-idempotenten Änderungen jedoch potenziell schädlich.
  • Die generierte API-Schicht soll aktualisierbar bleiben, während die öffentliche, ergonomische Schnittstelle stabil und verständlich bleibt.

02 — Verantwortung

Meine Rolle

Ich habe das Paket entworfen, implementiert, getestet, dokumentiert und als erste eigene Rust-Bibliothek veröffentlicht. Dazu gehörten sowohl die API-Abstraktion als auch Scheduler, Fehlerstrategie, CI und der Release-Prozess.

  1. 01Architektur der generierten und handgeschriebenen API-Schichten
  2. 02Entwurf des prioritätsgesteuerten Schedulers und der Starvation-Vermeidung
  3. 03Klassifikation von Fehlern und operationsabhängige Retry-Regeln
  4. 04Teststrategie für zeit- und netzwerkabhängiges Verhalten
  5. 05Dokumentation, Paketierung, Lizenzprüfung und automatisierte Veröffentlichung

03 — Umsetzung

Ansatz & Entscheidungen

Die Lösung trennt mechanisch generierte API-Bausteine von einer bewusst kleinen, handgeschriebenen Client-Abstraktion. Dadurch kann die OpenAPI-Spezifikation nachgezogen werden, ohne die Nutzung des Clients vollständig an die generierte Oberfläche zu koppeln.

D01

Prioritäten mit Fairness

Ein Token-Bucket-Scheduler koordiniert Anfragen in drei Prioritätsstufen. Wartende Aufgaben altern schrittweise in eine höhere effektive Priorität, damit kontinuierliche kritische Last andere Arbeit nicht dauerhaft blockiert.

D02

Retries nach Operationsrisiko

Antworten mit Retry-After werden berücksichtigt, temporäre Fehler erhalten exponentielles Backoff mit Jitter. Lesende und potenziell nicht-idempotente Operationen werden unterschiedlich behandelt, um unbeabsichtigte Doppelaktionen zu vermeiden.

D03

Beobachtbares Verhalten

Tracing-Spans und Aktivitätsmetriken machen Wartezeiten, Ausführung und Fehler sichtbar. Das unterstützt sowohl die Fehlersuche als auch die Bewertung des Schedulers unter realistischen Lastmustern.

D04

Release als Teil der Qualität

Die CI prüft Formatierung, statische Analyse, Tests, Dokumentation, Spezifikationsabweichungen und Releases. Nicht weiterverteilbare Bestandteile der API-Spezifikation bleiben bewusst außerhalb des veröffentlichten Pakets.

04 — Technologie

Technischer Rahmen

  • Rust
  • Tokio
  • reqwest
  • serde
  • OpenAPI
  • progenitor
  • wiremock
  • GitLab CI
  • Nix

05 — Rückblick

Ergebnis & Erkenntnisse

Version 0.1.0 ist seit dem 18. Juni 2026 unter der MIT-Lizenz auf crates.io verfügbar. Die öffentliche API-Dokumentation wird über docs.rs bereitgestellt; Quelltext und Entwicklungsverlauf sind im GitLab-Projekt nachvollziehbar.

Das Ergebnis ist eine wiederverwendbare Client-Grundlage, die API-Typen, kontrollierte Parallelität und eine vorsichtige Fehlerstrategie zusammenführt. Veränderliche Downloadzahlen werden bewusst nicht als Erfolgskennzahl verwendet.

  • L01Rate Limiting ist eine fachliche Eigenschaft des Clients und nicht nur eine Wartezeit vor einzelnen Requests.
  • L02Priorisierung braucht eine explizite Fairness-Strategie, sobald dauerhaft unterschiedlich dringende Arbeit anfällt.
  • L03Retry-Entscheidungen müssen die Semantik einer Operation berücksichtigen, nicht nur den HTTP-Status.
  • L04Lizenz- und Paketierungsgrenzen gehören früh in den Release-Prozess.