go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/cv/api/v1/PubSub.README.md (about)

     1  # CV PubSub Messages
     2  
     3  The `pubsub.proto` includes the proto messages of the PubSub topics, where CV
     4  publishes messages for CV run events.
     5  
     6  ## Subscribing to CV topics
     7  
     8  Currently, access to all the CV topics are protected by ACL. To subscribe
     9  to CV topics, contact [g/luci-eng] or file a bug at [go/luci-bug-admin] to
    10  request access to the CV topics.
    11  
    12  [g/luci-eng]: http://g/luci-eng
    13  [go/luci-bug-admin]: http://go/luci-bug-admin
    14  
    15  ## Topics
    16  
    17  NOTE: Due to the nature of Cloud PubSub, duplicate messages may be delivered
    18  for a single Run event. However, it's guaranteed that at least one message will
    19  be delivered for each Run event.
    20  
    21  NOTE: Message formats can be updated with additional fields in the future,
    22  and all messages are encoded in [JSONPB]. Ignore unknown fields when decoding
    23  the payload to avoid breakages.
    24  
    25  [JSONPB]: https://developers.google.com/protocol-buffers/docs/proto3#json).
    26  
    27  ### RunEnded
    28  - Topic: `projects/luci-change-verifier/topics/v1.run_ended`
    29  - Message Format: https://pkg.go.dev/go.chromium.org/luci/cv/api/v1#PubSubRun
    30  - Attributes:
    31    - `luci_project`: the LUCI project the CV Run belongs to.
    32    - `status`: the terminal status of the CV Run. Visit [RunStatus] for a list of
    33      terminal statuses.
    34  - Description: When a CV Run changes to a terminal status, RunEnded event will
    35    be published into this topic, and the status field tells the reason of the
    36    termination.
    37  
    38  [RunStatus]: https://pkg.go.dev/go.chromium.org/luci/cv/api/v1#Run_Status
    39  
    40  ## Adding a new topic
    41  
    42  1. Update the terraform config to create a new topic.
    43  2. Add a new proto message for the topic in this folder, if necessary.
    44  3. Register a new TaskClass and add utility functions for the new topic in
    45  cv/internal/run/pubsub.
    46  4. Update this doc with the new topic.
    47