DOCSEARCHbyAlgolia
Submit Docs

Cocoon

repository·main·Indexed 42 days ago

https://github.com/flutter/cocoon

A backend runtime built on Dart App Engine that coordinates and aggregates build results from the Flutter repository to provide a monitoring dashboard. The project also includes several CIPD-distributed tooling utilities: a codesign tool for Mac engine binaries, device_doctor for managing Flutter LUCI swarming bot health, and packaging scripts for Doxygen and ktlint.

Tokens
27.2K
Snippets
85
Records
147
Agent score
50%

What's inside Cocoon

  1. Overview of Cocoon Code Health

    main

    The cocoon_code_health package contains tests and tools designed to maintain the health of the flutter/cocoon repository.

    Note on overlap: This package currently shares some responsibilities with the root analyze package. However, all new functionality should be implemented within cocoon_code_health, and existing functionality should be migrated from analyze to this package over time.

  2. Overview of Cocoon Commons

    main

    The cocoon_common package provides shared functionality, code, and interfaces used across various Cocoon services and user interfaces. It serves as a central repository for logic that is common to multiple packages within the flutter/cocoon repository.

    Key consumers of this package include:

    • app_dart
    • auto_submit
    • dashboard

  4. What is Cocoon

    main

    Cocoon is a Dart App Engine custom runtime (backend) paired with a Flutter-based frontend (build and repository dashboard). Its primary purpose is to coordinate and aggregate the results of flutter/flutter builds.

    Note: Cocoon is not intended for general Flutter app development and is not a Google product.

  7. Use the Cocoon integration testing infrastructure

    main
    For full-stack integration testing, use the packages/cocoon_integration_test package. This package provides an offline environment equipped with functional fakes for all Google Cloud Platform (GCP) and external services. This allows you to run integration tests without requiring live connections to external APIs or cloud infrastructure.

  8. Guidelines for contributing to Cocoon Commons

    main

    When deciding whether to add code to cocoon_common, follow these architectural constraints:

    Include code if:

    • It is shared code or an interface used directly by one or more packages within the flutter/cocoon repository.

    Do NOT include code if:

    • It depends on running on a server (use cocoon_server instead).
    • It imports or uses the Flutter SDK.
    • It is intended for use outside of the flutter/cocoon repository.
    • It is used exclusively for testing (use cocoon_common_test instead).

  9. Understand Presubmit Scheduling in the Monorepo

    main

    In the Cocoon monorepo, presubmit checks are managed via .ci.yaml files. The scheduling process involves a validation step and actual test execution.

    Key Concepts

    • ci.yaml validation: This is the primary required check. If this check passes, the PR can technically be submitted (unless blocked by other means), as it only validates the configuration files themselves, not the actual code changes.
    • autosubmit label: To prevent users with commit access from bypassing actual testing after the validation check passes, use the autosubmit label. This ensures that the system waits for all scheduled checks to pass before allowing a merge.
    • Engine Changes: If a PR contains changes to the engine, Cocoon must schedule and wait for all engine builds to be present to allow testing from source. This is managed via an engine sentinel check to block progress until engine builds are ready.

  10. Reliability and error handling requirements

    main

    To ensure high data fidelity and system usability, implement the following error handling patterns:

    • Resilience through Automation: Use robust retry logic to automatically handle transient failures, such as GitHub API timeouts or LUCI build-bucket flakes.
    • Graceful Degradation: The dashboard must remain functional if partial data is missing. If a service (e.g., BigQuery or a specific LUCI project) is unavailable, the UI must clearly indicate the limitation while still serving other available information.
    • Verbose Debugging Context: When errors occur, provide technical context including trace IDs, error codes, and source references in logs and internal UI views to facilitate rapid diagnosis by EngProd.

  11. How Monorepo Scheduling handles Engine builds

    main

    When a Pull Request contains engine changes, Cocoon follows a specific orchestration flow to ensure testing is performed against the correct source builds:

    1. Identify Engine Changes: Cocoon detects changes in /engine/src/flutter/.ci/yaml.
    2. Engine Sentinel: A engine sentinel check is created on GitHub to block the PR.
    3. Schedule Engine Builds: Cocoon requests engine builds via luci.
    4. Wait for Completion: Cocoon waits for the check_run status updates from GitHub for all engine builds.
    5. Final Validation:
      • If all engine builds succeed: The engine sentinel is marked as success, and Cocoon proceeds to schedule the remaining presubmit targets (framework or other targets) using getPresubmitTargets and getTriggerList.
      • If any engine build fails: Both the engine sentinel and ci.yaml validation are marked as failure, blocking the PR.

  12. Implement MergeQueueState for dashboard state management

    main

    The MergeQueueState class (located in dashboard/lib/state/merge_queue.dart) manages the dashboard's data lifecycle by extending ChangeNotifier. It integrates CocoonService and FirebaseAuthService to handle the following:

    • Data Fetching: Manages state variables for loading status, error states (including 403 Forbidden), and the list of filtered data.
    • Filtering: Provides logic to search/filter the queue by commit hash, ref, and message.
    • Resend Debounce: Implements a 3-second debounce logic for the replay action to prevent rapid-fire requests.
    • Auto-Refresh: Implements auto-refresh logic based on a user-selectable interval.