Add protolint (#9)

.github/workflows/protolint.yaml

@@ -0,0 +1,39 @@
+---
+name: Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  merge_group:
+    branches: ["**"]
+
+permissions: { }
+
+jobs:
+  build:
+    name: Protolint
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: read
+      # To report GitHub Actions status checks
+      statuses: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          # super-linter needs the full git history to get the
+          # list of files that changed across commits
+          fetch-depth: 0
+
+      - name: Lint protocol buffers
+        uses: super-linter/super-linter@v6
+        env:
+          # To report GitHub Actions status checks
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          LINTER_RULES_PATH: .
+          PROTOBUF_CONFIG_FILE: .protolint.yaml
+          VALIDATE_PROTOBUF: true

.protolint.yaml

@@ -0,0 +1,19 @@
+---
+lint:
+  # Run `protolint list` to see all available rules.
+  rules:
+    all_default: true
+
+    # The specific linters to remove.
+    remove:
+      - REPEATED_FIELD_NAMES_PLURALIZED
+      - FIELD_NAMES_EXCLUDE_PREPOSITIONS
+      - MESSAGE_NAMES_EXCLUDE_PREPOSITIONS
+      - RPCS_HAVE_COMMENT
+      - FIELDS_HAVE_COMMENT
+      - ENUM_FIELDS_HAVE_COMMENT
+  rules_option:
+    # MAX_LINE_LENGTH rule option.
+    max_line_length:
+      max_chars: 120
+      tab_chars: 2

apis/workflows/v1/core.proto

@@ -1,3 +1,5 @@
+// Core types for workflows.
+
 syntax = "proto3";
 
 package workflows.v1;
@@ -22,10 +24,12 @@ message Job {
 // A task is a single unit of work.
 message Task {
   UUID id = 1;  // The id of the task instance. Contains the submission timestamp as the time part of the ULID.
-  TaskIdentifier identifier = 2;  // Unique identifier for the task. Used by runners to match tasks to specific functions.
+  // Unique identifier for the task. Used by runners to match tasks to specific functions.
+  TaskIdentifier identifier = 2;
   TaskState state = 3;  // The current state of the task.
   optional bytes input = 4; // The serialized input parameters for the task in the format that this task expects.
-  optional string display = 5; // Display is a human readable representation of the Task used for printing or visualizations
+  // Display is a human readable representation of the Task used for printing or visualizations
+  optional string display = 5;
   Job job = 6;  // The job that this task belongs to.
   UUID parent_id = 7;  // The id of the parent task.
   repeated UUID depends_on = 8;  // The ids of the tasks that this task depends on.
@@ -35,12 +39,18 @@ message Task {
 
 // The state of a task.
 enum TaskState {
-  UNDEFINED = 0;
-  QUEUED = 1;  // The task is queued and waiting to be run.
-  RUNNING = 2;  // The task is currently running on some task runner.
-  COMPUTED = 3;  // The task has been computed and the output is available. If the task also has no more outstanding children, it is considered COMPLETED.
-  FAILED = 4;  // The task has failed.
-  CANCELLED = 5;  // The task has been cancelled due to user request.
+  TASK_STATE_UNSPECIFIED = 0;
+  // The task is queued and waiting to be run.
+  TASK_STATE_QUEUED = 1;
+  // The task is currently running on some task runner.
+  TASK_STATE_RUNNING = 2;
+  // The task has been computed and the output is available.
+  // If the task also has no more outstanding children, it is considered COMPLETED.
+  TASK_STATE_COMPUTED = 3;
+  // The task has failed.
+  TASK_STATE_FAILED = 4;
+  // The task has been cancelled due to user request.
+  TASK_STATE_CANCELLED = 5;
 }
 
 // An identifier for a task.
@@ -60,7 +70,8 @@ message TaskSubmission {
   TaskIdentifier identifier = 2; // The task identifier
   bytes input = 3; // The serialized task instance
   string display = 4; // A human-readable description of the task
-  repeated int64 dependencies = 5; // A list of indices, corresponding to tasks in the list of sub_tasks that this SubTask is part of.
+  // A list of indices, corresponding to tasks in the list of sub_tasks that this SubTask is part of.
+  repeated int64 dependencies = 5;
   int64 max_retries = 6; // The maximum number of retries for this task.
 }
 
@@ -69,6 +80,7 @@ message UUID {
   bytes uuid = 1;
 }
 
+// A lease for a task.
 message TaskLease {
   google.protobuf.Duration lease = 1;
   google.protobuf.Duration recommended_wait_until_next_extension = 2;

apis/workflows/v1/diagram.proto

@@ -1,26 +1,39 @@
+// Diagram service for rendering diagrams
+
 syntax = "proto3";
 
 package workflows.v1;
 
 import "workflows/v1/core.proto";
 
+// Request to render a diagram
 message RenderDiagramRequest {
   string diagram = 1;  // The diagram graph in the D2 syntax
   RenderOptions render_options = 2;  // The options for rendering the diagram
 }
 
+// Options for rendering the diagram
 message RenderOptions {
-  string layout = 1;  // The layout to use for rendering the diagram: https://d2lang.com/tour/layouts/. "dagre" or "elk". Defaults to "dagre"
-  optional int64 theme_id = 2;  // The theme to use for rendering the diagram: https://d2lang.com/tour/themes/
-  bool sketchy = 3;  // Whether to render the diagram in a sketchy (hand-drawn) style
-  int64 padding = 4;  // The padding around the diagram
-  string direction = 5;  // Set explicitly the direction of the diagram: https://d2lang.com/tour/layouts/#direction. "up", "down", "right", "left".
+  // The layout to use for rendering the diagram: https://d2lang.com/tour/layouts/.
+  // "dagre" or "elk". Defaults to "dagre"
+  string layout = 1;
+  // The theme to use for rendering the diagram: https://d2lang.com/tour/themes/
+  optional int64 theme_id = 2;
+  // Whether to render the diagram in a sketchy (hand-drawn) style
+  bool sketchy = 3;
+  // The padding around the diagram
+  int64 padding = 4;
+  // Set explicitly the direction of the diagram: https://d2lang.com/tour/layouts/#direction.
+  // "up", "down", "right", "left".
+  string direction = 5;
 }
 
+// A rendered diagram
 message Diagram {
   bytes svg = 1;
 }
 
+// The diagram service
 service DiagramService {
   rpc Render(RenderDiagramRequest) returns (Diagram);
 }

apis/workflows/v1/job.proto

@@ -54,6 +54,7 @@ message VisualizeJobRequest {
   RenderOptions render_options = 2;
 }
 
+// A service for interacting with jobs.
 service JobService {
   rpc SubmitJob(SubmitJobRequest) returns (Job);
   rpc GetJob(GetJobRequest) returns (Job);

apis/workflows/v1/task.proto

@@ -12,7 +12,8 @@ import "workflows/v1/core.proto";
 // NextTaskRequest is the request for requesting the next task to run and marking a task as computed.
 message NextTaskRequest {
   optional ComputedTask computed_task = 1;  // The task that has been computed. If not set, the next task will
-  optional NextTaskToRun next_task_to_run = 2;  // The capabilities of the task runner, and therefore the potential tasks that can be run by that task runner.
+  // The capabilities of the task runner, and therefore the potential tasks that can be run by that task runner.
+  optional NextTaskToRun next_task_to_run = 2;
 }
 
 // NextTaskToRun is a message specifying the capabilities of the task runner, and therefore the potential
@@ -25,7 +26,9 @@ message NextTaskToRun {
 // ComputedTask is a message specifying a task that has been computed by the task runner.
 message ComputedTask {
   UUID id = 1;  // The id of the task that has been computed.
-  string display = 2;  // A display name for the task that has been computed for visualization purposes. If not set, the display message specified upon task submission will be kept.
+  // A display name for the task that has been computed for visualization purposes.
+  // If not set, the display message specified upon task submission will be kept.
+  string display = 2;
   repeated TaskSubmission sub_tasks = 3;  // A list of sub-tasks that the just computed task spawned.
 }
 
@@ -43,16 +46,19 @@ message TaskFailedRequest {
   bool cancel_job = 3;
 }
 
-// TaskStateResponse is the response to the TaskFailed request, indicating the current state of the task marked as failed.
+// TaskStateResponse is the response to the TaskFailed request,
+// indicating the current state of the task marked as failed.
 message TaskStateResponse {
   TaskState state = 1;
 }
 
+// TaskLease is a message specifying the new lease expiration time of a task.
 message TaskLeaseRequest {
   UUID task_id = 1;
   optional google.protobuf.Duration requested_lease = 2;
 }
 
+// A service for task runners to communicate with the workflows service.
 service TaskService {
   // NextTask marks a task as computed and asks for the next task to run.
   // If no task marked as computed is sent, it is assumed that the task runner just started up or was idling so
@@ -64,7 +70,8 @@ service TaskService {
   rpc NextTask(NextTaskRequest) returns (NextTaskResponse);
 
   // TaskFailed tells the task server that we have failed to compute a task.
-  // The task server will then mark the task as queued or failed, depending on the retry policy, and possibly cancel the job.
+  // The task server will then mark the task as queued or failed, depending on the retry policy,
+  // and possibly cancel the job.
   // If a task runner wants to continue executing tasks, it should afterwards fetch a new one using GetTaskToRun.
   rpc TaskFailed(TaskFailedRequest) returns (TaskStateResponse);
 

apis/workflows/v1/timeseries.proto

@@ -1,20 +1,24 @@
+// Timeseries types for workflows
+
 syntax = "proto3";
 
 package workflows.v1;
 
 import "workflows/v1/core.proto";
 
-import "google/protobuf/timestamp.proto";
 import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
 
 // TimeInterval is a message that represents a time interval, with a start and end time.
 // copied from datasets/v1/datasets.proto until we figure out how to import across packages
 message TimeInterval {
   google.protobuf.Timestamp start_time = 1; // Start time of the interval.
   google.protobuf.Timestamp end_time = 2; // End time of the interval.
 
-  bool start_exclusive = 3;  // Flag indicating whether the start time is exclusive. If true, the start time is not included in the interval.
-  bool end_inclusive = 4;  // Flag indicating whether the end time is inclusive. If true, the end time is included in the interval.
+  // Flag indicating whether the start time is exclusive. If true, the start time is not included in the interval.
+  bool start_exclusive = 3;
+  // Flag indicating whether the end time is inclusive. If true, the end time is included in the interval.
+  bool end_inclusive = 4;
 }
 
 // DatapointInterval is a message that represents a datapoint interval, with a start and end datapoint.
@@ -23,6 +27,7 @@ message DatapointInterval {
   UUID end = 2;
 }
 
+// TimeseriesDatasetChunk is a message that represents a chunk of a timeseries dataset.
 message TimeseriesDatasetChunk {
   UUID dataset_id = 1;
   UUID collection_id = 2;
@@ -33,6 +38,7 @@ message TimeseriesDatasetChunk {
   int64 datapoints_per_365_days = 7;
 }
 
+// TimeChunk is a message that represents a time interval and a chunk size.
 message TimeChunk {
   TimeInterval time_interval = 1;
   google.protobuf.Duration chunk_size = 2;

apis/workflows/v1/workflows.proto

@@ -38,6 +38,7 @@ message ListClustersResponse {
   repeated Cluster clusters = 1;
 }
 
+// A service for managing workflows.
 service WorkflowsService {
   rpc CreateCluster(CreateClusterRequest) returns (Cluster);
   rpc GetCluster(GetClusterRequest) returns (Cluster);