Merge pull request #687 from dart-lang/merge-bazel_worker-package

Merge `package:bazel_worker`

.github/ISSUE_TEMPLATE/bazel_worker.md

@@ -0,0 +1,5 @@
+---
+name: "package:bazel_worker"
+about: "Create a bug or file a feature request against package:bazel_worker."
+labels: "package:bazel_worker"
+---

.github/labeler.yml

@@ -4,6 +4,10 @@
   - changed-files:
       - any-glob-to-any-file: '.github/**'
 
+'package:bazel_worker':
+  - changed-files:
+      - any-glob-to-any-file: 'pkgs/bazel_worker/**'
+
 'package:boolean_selector':
   - changed-files:
       - any-glob-to-any-file: 'pkgs/boolean_selector/**'

.github/workflows/bazel_worker.yaml

@@ -0,0 +1,41 @@
+name: package:bazel_worker
+
+on:
+  # Run on PRs and pushes to the default branch.
+  push:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/bazel_worker.yml'
+      - 'pkgs/bazel_worker/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - '.github/workflows/bazel_worker.yml'
+      - 'pkgs/bazel_worker/**'
+  schedule:
+    - cron: "0 0 * * 0"
+
+env:
+  PUB_ENVIRONMENT: bot.github
+
+
+defaults:
+  run:
+    working-directory: pkgs/bazel_worker/
+
+jobs:
+  # Run the test script against the latest dev build.
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        sdk: [3.1.0, dev]
+    steps:
+      - uses: actions/checkout@d632683dd7b4114ad314bca15554477dd762a938
+      - uses: dart-lang/setup-dart@0a8a0fc875eb934c15d08629302413c671d3f672
+        with:
+          sdk: ${{ matrix.sdk }}
+      - run: "dart format --output=none --set-exit-if-changed ."
+      - name: Test
+        run: ./tool/travis.sh

README.md

@@ -14,6 +14,7 @@ don't naturally belong to other topic monorepos (like
 
 | Package | Description | Version |
 | --- | --- | --- |
+| [bazel_worker](pkgs/bazel_worker/) | Protocol and utilities to implement or invoke persistent bazel workers. | [![pub package](https://img.shields.io/pub/v/bazel_worker.svg)](https://pub.dev/packages/bazel_worker) |
 | [boolean_selector](pkgs/boolean_selector/) | A flexible syntax for boolean expressions, based on a simplified version of Dart's expression syntax. | [![pub package](https://img.shields.io/pub/v/boolean_selector.svg)](https://pub.dev/packages/boolean_selector) |
 | [browser_launcher](pkgs/browser_launcher/) | Provides a standardized way to launch web browsers for testing and tools. | [![pub package](https://img.shields.io/pub/v/browser_launcher.svg)](https://pub.dev/packages/browser_launcher) |
 | [cli_config](pkgs/cli_config/) | A library to take config values from configuration files, CLI arguments, and environment variables. | [![pub package](https://img.shields.io/pub/v/cli_config.svg)](https://pub.dev/packages/cli_config) |

pkgs/bazel_worker/.gitignore

@@ -0,0 +1,10 @@
+.buildlog
+.DS_Store
+.idea
+.pub/
+.settings/
+build/
+packages
+.packages
+pubspec.lock
+.dart_tool

pkgs/bazel_worker/AUTHORS

@@ -0,0 +1,6 @@
+# Below is a list of people and organizations that have contributed
+# to the project. Names should be added to the list like so:
+#
+#   Name/Organization <email address>
+
+Google Inc.

pkgs/bazel_worker/CHANGELOG.md

@@ -0,0 +1,189 @@
+## 1.1.2
+
+* Require Dart SDK `^3.1.0`.
+* Move to `dart-lang/tools` monorepo.
+
+## 1.1.1
+
+* Fix a bug where if spawnWorker threw an error, work requests would hang
+  forever instead of failing.
+
+## 1.1.0
+
+* Add constructors with named parameters to
+  the generated worker protocol messages.
+* Include comments on the generated worker protocol API.
+
+## 1.0.3
+
+* Require `package:protobuf` >= 3.0.0.
+* Require Dart SDK >= 2.19.0
+
+## 1.0.2
+
+* Expand pub documentation to improve pub score.
+
+## 1.0.1
+
+* Require Dart SDK >=2.14.0
+* Drop dependency on `package:pedantic`.
+
+## 1.0.0
+
+* Improve `AsyncMessageGrouper` performance.
+* Add `benchmark/benchmark.dart` measuring `AsyncMessageGrouper` performance.
+
+## 1.0.0-nullsafety.0
+
+* Migrate to null safety.
+* Use `WorkResponse` with `exitCode` set to `EXIT_CODE_BROKEN_PIPE` instead of
+  `null` responses.
+
+## 0.1.25+1-dev
+
+* Regenerate proto code and fix some new analysis hints.
+
+## 0.1.25
+
+* Add `isBroadcast` implementation to `TestStdin` classes.
+
+## 0.1.24
+
+* Check for closed port when trying to read a response in
+  `IsolateDriverConnection` and return `null` if there is nothing to be read.
+
+## 0.1.23+1
+
+* Don't rely on `exitCode` to know when a worker terminates, instead wait for
+  the input stream to close.
+  * The SDK may also start throwing instead of returning a `null` here, so this
+    pre-emptively guards against that.
+
+## 0.1.23
+
+* Support protobuf `1.x`.
+* Added a tool for updating generated proto files and updated them
+  using the latest version of the protoc_plugin package.
+  * This required a lower bound bump of the `protobuf` package to `0.14.4`.
+
+## 0.1.22
+
+* Require protobuf 0.14.0.
+
+## 0.1.21+1
+
+* Don't rely on `exitCode` to know when a worker terminates, instead wait for
+  the input stream to close. Backport of fix in `0.1.23+1` in a version that
+  does not require a newer protobuf.
+
+## 0.1.21
+
+* Make `TestStdinAsync` behave like a `Stream<Uint8List>`
+
+## 0.1.20
+
+* Close worker `outputStream` on `cancel`.
+
+## 0.1.19
+
+* Work around https://github.com/dart-lang/sdk/issues/35874.
+
+## 0.1.18
+
+* Add a `trackWork` optional named argument to `BazelDriver.doWork`. This allows
+  the caller to know when a work request is actually sent to a worker.
+
+## 0.1.17
+
+* Allow protobuf 0.13.0.
+
+## 0.1.16
+
+* Update the worker_protocol.pb.dart file with the latest proto generator.
+* Require protobuf 0.11.0.
+
+## 0.1.15
+
+* Update the worker_protocol.pb.dart file with the latest proto generator.
+* Require protobuf 0.10.4.
+
+## 0.1.14
+
+* Allow workers to support running in isolates. To support running in isolates,
+  workers must modify their `main` method to accept a `SendPort` then use it
+  when creating the `AsyncWorkerConnection`. See `async_worker` in `e2e_test`.
+
+## 0.1.13
+
+* Support protobuf 0.10.0.
+
+## 0.1.12
+
+* Set max SDK version to `<3.0.0`.
+
+## 0.1.11
+
+* Added support for protobuf 0.9.0.
+
+## 0.1.10
+
+* Update the SDK dependency to 2.0.0-dev.17.0.
+* Update to protobuf version 0.8.0
+* Remove usages of deprecated upper-case constants from the SDK.
+
+## 0.1.9
+
+* Update the worker_protocol.pb.dart file with the latest proto generator.
+
+## 0.1.8
+
+* Add `Future cancel()` method to `DriverConnection`, which in the case of a
+  `StdDriverConnection` closes the input stream.
+  * The `terminateWorkers` method on `BazelWorkerDriver` now calls `cancel` on
+    all worker connections to ensure the vm can exit correctly.
+
+## 0.1.7
+
+* Update the `BazelWorkerDriver` class to handle worker crashes, and retry work
+  requests. The number of retries is configurable with the new `int maxRetries`
+  optional arg to the `BazelWorkerDriver` constructor.
+
+## 0.1.6
+
+* Update the worker_protocol.pb.dart file with the latest proto generator.
+* Add support for package:async 2.x and package:protobuf 6.x.
+
+## 0.1.5
+
+* Change TestStdinAsync.controller to StreamController<List<int>> (instead of
+  using dynamic as the type argument).
+
+## 0.1.4
+
+* Added `BazelWorkerDriver` class, which can be used to implement the bazel side
+  of the protocol. This allows you to speak to any process which knows the bazel
+  protocol from your own process.
+* Changed `WorkerConnection#readRequest` to return a `FutureOr<WorkRequest>`
+  instead of dynamic.
+
+## 0.1.3
+
+* Add automatic intercepting of print calls and append them to
+  `response.output`. This makes more libraries work out of the box, as printing
+  would previously cause an error due to communication over stdin/stdout.
+  * Note that using stdin/stdout directly will still cause an error, but that is
+    less common.
+
+## 0.1.2
+
+* Add better handling for the case where stdin gives an error instead of an EOF.
+
+## 0.1.1
+
+* Export `AsyncMessageGrouper` and `SyncMessageGrouper` as part of the testing
+  library. These can assist when writing e2e tests and communicating with a
+  worker process.
+
+## 0.1.0
+
+* Initial version.

pkgs/bazel_worker/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2016, the Dart project authors. 
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/bazel_worker/README.md

@@ -0,0 +1,66 @@
+Tools for creating a persistent worker loop for [bazel](https://bazel.build/).
+
+## Usage
+
+There are two abstract classes provided by this package, `AsyncWorkerLoop` and
+`SyncWorkerLoop`. These each have a `performRequest` method which you must
+implement.
+
+Lets look at a simple example of a `SyncWorkerLoop` implementation:
+
+```dart
+import 'dart:io';
+import 'package:bazel_worker/bazel_worker.dart';
+
+void main() {
+  // Blocks until it gets an EOF from stdin.
+  SyncSimpleWorker().run();
+}
+
+class SyncSimpleWorker extends SyncWorkerLoop {
+  /// Must synchronously return a [WorkResponse], since this is a
+  /// [SyncWorkerLoop].
+  WorkResponse performRequest(WorkRequest request) {
+    File('hello.txt').writeAsStringSync('hello world!');
+    return WorkResponse()..exitCode = EXIT_CODE_OK;
+  }
+}
+```
+
+And now the same thing, implemented as an `AsyncWorkerLoop`:
+
+```dart
+import 'dart:io';
+import 'package:bazel_worker/bazel_worker.dart';
+
+void main() {
+  // Doesn't block, runs tasks async as they are received on stdin.
+  AsyncSimpleWorker().run();
+}
+
+class AsyncSimpleWorker extends AsyncWorkerLoop {
+  /// Must return a [Future<WorkResponse>], since this is an
+  /// [AsyncWorkerLoop].
+  Future<WorkResponse> performRequest(WorkRequest request) async {
+    await File('hello.txt').writeAsString('hello world!');
+    return WorkResponse()..exitCode = EXIT_CODE_OK;
+  }
+}
+```
+
+As you can see, these are nearly identical, it mostly comes down to the
+constraints on your package and personal preference which one you choose to
+implement.
+
+## Testing
+
+A `package:bazel_worker/testing.dart` file is also provided, which can greatly
+assist with writing unit tests for your worker. See the
+`test/worker_loop_test.dart` test included in this package for an example of how
+the helpers can be used.
+
+## Features and bugs
+
+Please file feature requests and bugs at the [issue tracker][tracker].
+
+[tracker]: https://github.com/dart-lang/tools/issues

pkgs/bazel_worker/analysis_options.yaml

@@ -0,0 +1,13 @@
+# https://dart.dev/guides/language/analysis-options
+include: package:dart_flutter_team_lints/analysis_options.yaml
+
+analyzer:
+  language:
+    strict-casts: true
+  errors:
+    # For the generated file
+    lines_longer_than_80_chars: ignore
+
+linter:
+  rules:
+    - package_api_docs