go/firebase
1
0
Fork 0
Code Issues Pull Requests Packages Releases 1 Activity

1 Release 1 Tag

RSS Feed
  • v0.9.0 3ef30c2354
    Compare

    Release v0.9.0 Stable

    Rene Nochebuena released this 2026-03-19 07:36:13 -06:00 | 0 commits to main since this release

    v0.9.0

    code.nochebuena.dev/go/firebase

    Overview

    firebase manages the lifecycle of a firebase.google.com/go/v4 App: validates
    configuration at init time, initialises the SDK App, exposes the native *firebase.App
    to consumers, and performs health checks by probing the Firebase Auth service.

    This is the initial stable release. The API has been designed through multiple architecture
    reviews and validated end-to-end via the todo-api POC. It is versioned v0.9.0 rather than
    v1.0.0 because it has not yet been exercised across all production edge cases, and minor
    API refinements may follow.

    What's Included

    • Config — connection settings loaded from environment variables:
      • FIREBASE_PROJECT_ID (required) — Google Cloud project ID; the SDK resolves
        credentials via Application Default Credentials (ADC)
    • Provider interface — App() *firebase.App for consumers that only need the SDK entry point
    • Component interface — embeds launcher.Component + health.Checkable + Provider for
      full lifecycle management
    • New(logger, cfg) Component — constructor; register with lc.Append(fb)
    • Health check — calls GetUser("health-probe-non-existent") on the Auth client and uses
      auth.IsUserNotFound(err) to confirm the Firebase Auth service is reachable; priority is
      health.LevelCritical
    • No-op OnStop — the Firebase Admin SDK has no Close method

    Installation

    go get code.nochebuena.dev/go/firebase@v0.9.0

    import "code.nochebuena.dev/go/firebase"

fb := firebase.New(logger, firebase.Config{
    ProjectID: "my-project",
})
lc.Append(fb)

    Credentials are resolved via Application Default Credentials.
    In production, set GOOGLE_APPLICATION_CREDENTIALS to the path of a service account JSON
    file or run on a GCP environment with an attached service account.

    Design Highlights

    Native *firebase.App exposed directly. App() returns the SDK entry point unchanged.
    Callers call app.Auth(ctx), app.Firestore(ctx), etc. themselves. The module does not
    cache or pre-construct service-specific clients.

    Health check via known-nonexistent UID. HealthCheck calls GetUser with the
    sentinel UID "health-probe-non-existent". A UserNotFound error from Firebase Auth
    confirms the service is reachable and healthy. Any other error (network failure, auth
    misconfiguration) is treated as a health failure. This avoids fragile string matching on
    error messages.

    Critical health priority. Priority() returns health.LevelCritical. A Firebase Auth
    outage is considered a critical failure for services that depend on token verification.

    Provider / Component split. Inject Provider into services that only need App().
    Inject Component only at the lifecycle registration site.

    Known Limitations & Edge Cases

    • The health check makes a live API call to Firebase Auth on every probe. Do not poll
      more frequently than every 30 seconds to avoid unnecessary quota consumption.
    • OnStop is a no-op log statement. The Firebase Admin SDK does not expose a Close
      method. In-flight SDK calls at shutdown must be handled by request context deadlines in
      the caller.
    • App() returns nil before OnInit has run. Guard against this in any code path that
      may execute before the launcher has initialised the component.
    • Credentials are managed entirely by the Firebase Admin SDK via ADC. This module does not
      accept or validate a credentials file path directly.

    v0.9.0 → v1.0.0 Roadmap

    • Validate health check behaviour under Firebase Auth quota limits and transient outages.
    • Evaluate caching the auth.Client instance inside the component to avoid per-call
      app.Auth(ctx) overhead in the health check.
    • Confirm graceful in-flight drain behaviour once the SDK exposes a Close mechanism.
    • Exercise long-running deployments with ADC credential refresh cycles.
    Downloads