googlechrome/webstatus-workers

webstatus-workers

This skill provides architectural and implementation details for the workers/ directory in webstatus.dev, which houses the event-driven notification pipeline.

Architecture

For a detailed breakdown of the notification pipeline architecture, including the event producer, push delivery dispatcher, and email sender, see references/architecture.md.

For guidance on adding future integrations (like Webhooks), see references/how-to-add-a-worker.md.

Canonical Data Transport & Event Semantics

Workers must use the shared structs in lib/workertypes/types.go for all incoming and outgoing messages. This ensures that a change in the Spanner schema or API doesn't immediately break the worker pipeline (decoupling).

Strict Rules for Data Sync:

• Event Payload Purity: Do not add display metadata (e.g., human-readable SearchName or user PII) to core data-sync pub/sub event schemas (e.g., FeatureDiffEvent, RefreshSearchCommand). Core events should represent the raw state change via canonical IDs (SearchID, EventID). Any display data needed for emails or UI should be fetched from Spanner at the last possible moment (Delivery/Render phase).
• Feature Differ "Added" Semantics: Within a FeatureDiff, the Added array represents features that newly matched the search query since the last run. It does NOT mean the feature just entered the web platform. Do not attempt to calculate baseline or status transitions against a "zero state" for features in the Added array, as this falsely reports them as "becoming" newly/widely available when they merely entered the search results.
• Browser Implementation Grouping: When formatting browser data for consumption (like combining Chrome Desktop and Chrome Android into a single row), the two implementations can ONLY be grouped if their entire transition state is identical. You must verify that From.Status, To.Status, To.Version, and To.Date perfectly match before combining them.

Local Development

• The workers run locally via Skaffold and connect to local emulators for Spanner (spanner:9010) and Pub/Sub (pubsub:8060).
• The FRONTEND_BASE_URL locally is usually http://localhost:5555.

Infrastructure Abstraction (The Adapter Pattern)

All workers must be decoupled from GCP-specific SDKs.

• Interfaces: Define the "What" (e.g., interface EmailSender) in the worker's package.
• Implementations: Put the "How" (e.g., struct PubSubSender) in lib/gcppubsub/gcppubsubadapters.
• This ensures workers are testable without Pub/Sub or GCS emulators.

General Guidelines

• DO cross-reference all code against the official Google Go Style Guide. If you are unsure about a specific style rule, DO NOT assume; you MUST ask the user for clarification.
• DO write tests for all new parsers, generators, and differ logic using table-driven tests.
• DO use the generic.OptionallySet[T] pattern when defining blob structures or canonical in-memory state to handle forward/backward compatibility gracefully (quiet rollouts).
• DON'T modify generated code.
• DO ensure the worker uses slog for logging and bubbles up transient errors using errors.Join(event.ErrTransientFailure, err) to NACK the message for retry.

Testing & Linting

• Precommit Suite: Run make precommit to execute the full suite of Go tests, formatting, and linting.
• Linting: Run make go-lint to lint all Go code using golangci-lint.
• Quick Test Iteration: Because this project uses a multi-module workspace (go.work), to run tests quickly for a single package without running the whole suite, execute go test from within the specific module directory:

  cd workers/<worker_name> && go test -v ./...
  

Documentation Updates

When you add a new worker, update the notification pipeline, or change data flow:

• Update docs/ARCHITECTURE.md to reflect the new pipeline step.
• Trigger the "Updating the Knowledge Base" prompt in GEMINI.md to ensure I am aware of the changes.
• Update these very skills files if you introduce new structural patterns or rules.

Critical Infrastructure Requirements

When adding a new worker, you MUST ensure that the manual instance counts are updated across all environments.

• Strict Object Types: The worker_manual_instance_counts variable in infra/variables.tf is an object type. This means that if you add a new field (e.g., webhook) to the object definition, every environment's .tfvars file (e.g., infra/.envs/staging.tfvars, infra/.envs/prod.tfvars) MUST be updated to include that field, or Terraform execution will fail.