# Proposed event contract, version 1 (AsyncAPI 3.0): the events this system publishes, their consumers, payloads and delivery
# guarantees, and the events it consumes. Status: proposal for review, not confirmed design.
asyncapi: 3.0.0
info:
  title: Releases Events
  version: 1.0.0
  description: 'Builds revoked, releases activated, paused and rolled back, installations enrolled and updated.
    Envelope, delivery guarantees and webhook headers: `common/v1/events.yaml`. Status: proposal for review, not
    confirmed design.'
defaultContentType: application/cloudevents+json
servers:
  prod:
    host: pubsub.googleapis.com
    protocol: googlepubsub
    description: Pub/Sub in the project that hosts the system, prod.
  stage:
    host: pubsub.googleapis.com
    protocol: googlepubsub
    description: Pub/Sub in the project that hosts the system, stage.
channels:
  releases.events.v1:
    address: releases.events.v1
    description: Every event releases publishes. Consumers filter by the `ce-type` attribute.
    messages:
      build_revoked_v1:
        $ref: '#/components/messages/build_revoked_v1'
      release_activated_v1:
        $ref: '#/components/messages/release_activated_v1'
      release_paused_v1:
        $ref: '#/components/messages/release_paused_v1'
      release_rolled_back_v1:
        $ref: '#/components/messages/release_rolled_back_v1'
      installation_enrolled_v1:
        $ref: '#/components/messages/installation_enrolled_v1'
      installation_updated_v1:
        $ref: '#/components/messages/installation_updated_v1'
    bindings:
      googlepubsub:
        messageRetentionDuration: 604800s
        schemaSettings:
          encoding: json
          name: projects/moonitoring-<env>-<project>/schemas/releases.events.v1
operations:
  publish_build_revoked_v1:
    action: send
    channel:
      $ref: '#/channels/releases.events.v1'
    messages:
    - $ref: '#/channels/releases.events.v1/messages/build_revoked_v1'
    summary: A build was revoked; it can no longer be released or rolled back to.
    x-moonitoring-producer: releases
    x-moonitoring-consumers: []
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '109.6'
    - '109.7'
  publish_release_activated_v1:
    action: send
    channel:
      $ref: '#/channels/releases.events.v1'
    messages:
    - $ref: '#/channels/releases.events.v1/messages/release_activated_v1'
    summary: 'A release became active on a channel: clients in its rollout receive the build at their next check.'
    x-moonitoring-producer: releases
    x-moonitoring-consumers:
    - farm
    x-moonitoring-webhook: true
    x-moonitoring-requirements:
    - '112'
    - '112.7'
    - '112.11'
  publish_release_paused_v1:
    action: send
    channel:
      $ref: '#/channels/releases.events.v1'
    messages:
    - $ref: '#/channels/releases.events.v1/messages/release_paused_v1'
    summary: A release stopped being offered.
    x-moonitoring-producer: releases
    x-moonitoring-consumers: []
    x-moonitoring-webhook: true
    x-moonitoring-requirements:
    - '112.7'
  publish_release_rolled_back_v1:
    action: send
    channel:
      $ref: '#/channels/releases.events.v1'
    messages:
    - $ref: '#/channels/releases.events.v1/messages/release_rolled_back_v1'
    summary: A channel was rolled back to an older build.
    x-moonitoring-producer: releases
    x-moonitoring-consumers:
    - farm
    x-moonitoring-webhook: true
    x-moonitoring-requirements:
    - '112'
  publish_installation_enrolled_v1:
    action: send
    channel:
      $ref: '#/channels/releases.events.v1'
    messages:
    - $ref: '#/channels/releases.events.v1/messages/installation_enrolled_v1'
    summary: A client enrolled on a channel.
    x-moonitoring-producer: releases
    x-moonitoring-consumers:
    - farm
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '118'
  publish_installation_updated_v1:
    action: send
    channel:
      $ref: '#/channels/releases.events.v1'
    messages:
    - $ref: '#/channels/releases.events.v1/messages/installation_updated_v1'
    summary: An installation reported an update, successful or not; its current build may have changed.
    x-moonitoring-producer: releases
    x-moonitoring-consumers:
    - farm
    x-moonitoring-webhook: false
    x-moonitoring-requirements:
    - '119'
    - '118.5'
components:
  messages:
    build_revoked_v1:
      name: build.revoked.v1
      title: build.revoked.v1
      summary: A build was revoked; it can no longer be released or rolled back to.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: build.revoked.v1
            subject:
              type: string
              description: The build id.
            data:
              $ref: '#/components/schemas/BuildRevokedV1Data'
    release_activated_v1:
      name: release.activated.v1
      title: release.activated.v1
      summary: 'A release became active on a channel: clients in its rollout receive the build at their next check.'
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: release.activated.v1
            subject:
              type: string
              description: The release id.
            data:
              $ref: '#/components/schemas/ReleaseActivatedV1Data'
    release_paused_v1:
      name: release.paused.v1
      title: release.paused.v1
      summary: A release stopped being offered.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: release.paused.v1
            subject:
              type: string
              description: The release id.
            data:
              $ref: '#/components/schemas/ReleasePausedV1Data'
    release_rolled_back_v1:
      name: release.rolled_back.v1
      title: release.rolled_back.v1
      summary: A channel was rolled back to an older build.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: release.rolled_back.v1
            subject:
              type: string
              description: The release id.
            data:
              $ref: '#/components/schemas/ReleaseRolledBackV1Data'
    installation_enrolled_v1:
      name: installation.enrolled.v1
      title: installation.enrolled.v1
      summary: A client enrolled on a channel.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: installation.enrolled.v1
            subject:
              type: string
              description: The installation id.
            data:
              $ref: '#/components/schemas/InstallationEnrolledV1Data'
    installation_updated_v1:
      name: installation.updated.v1
      title: installation.updated.v1
      summary: An installation reported an update, successful or not; its current build may have changed.
      traits:
      - $ref: ../../../common/v1/events.yaml#/components/messageTraits/Event
      payload:
        allOf:
        - $ref: ../../../common/v1/events.yaml#/components/schemas/EventEnvelope
        - type: object
          properties:
            type:
              type: string
              const: installation.updated.v1
            subject:
              type: string
              description: The installation id.
            data:
              $ref: '#/components/schemas/InstallationUpdatedV1Data'
  schemas:
    BuildRevokedV1Data:
      type: object
      properties:
        build:
          type: string
          format: uuid
        application:
          type: string
          format: uuid
        build_number:
          type: integer
        reason:
          type: string
      required:
      - build
      - application
      - build_number
      - reason
    ReleaseActivatedV1Data:
      type: object
      properties:
        release:
          type: string
          format: uuid
        channel:
          type: string
          format: uuid
        application:
          type: string
          format: uuid
        build:
          type: string
          format: uuid
        version_label:
          type: string
        rollout_pct:
          type: integer
        min_build_number:
          type: integer
        build_number:
          type: integer
          description: The build number, which clients compare with a minimum build on any channel.
        adapters:
          type: array
          description: 'The source adapters the build carries, as the client declares them in its catalog; only
            for a farm sync client. farm registers them (SourceAdapter, side client) from `release.activated.v1`.'
          items:
            type: object
            properties:
              code:
                type: string
                description: Stable name of the reader, e.g. `sialleva.export`.
              adapter_version:
                type: string
                description: Semantic version of the adapter.
              source_channel:
                type: string
                description: The name of the farm SourceChannel it reads, e.g. `SiAlleva` (unique in farm).
              supported_versions:
                type: string
                description: The source versions it was tested against, e.g. ">=3.0.1, <3.1".
            required:
            - code
            - adapter_version
            - source_channel
            - supported_versions
      required:
      - release
      - channel
      - application
      - build
      - version_label
      - rollout_pct
    ReleasePausedV1Data:
      type: object
      properties:
        release:
          type: string
          format: uuid
        channel:
          type: string
          format: uuid
        application:
          type: string
          format: uuid
      required:
      - release
      - channel
      - application
    ReleaseRolledBackV1Data:
      type: object
      properties:
        release:
          type: string
          format: uuid
        channel:
          type: string
          format: uuid
        application:
          type: string
          format: uuid
        build:
          type: string
          format: uuid
        version_label:
          type: string
      required:
      - release
      - channel
      - application
      - build
    InstallationEnrolledV1Data:
      type: object
      properties:
        installation:
          type: string
          format: uuid
        application:
          type: string
          format: uuid
        channel:
          type: string
          format: uuid
        platform:
          type: string
          format: uuid
        organization:
          type: string
          format: uuid
        current_build:
          type: string
          format: uuid
      required:
      - installation
      - application
      - channel
      - platform
    InstallationUpdatedV1Data:
      type: object
      properties:
        installation:
          type: string
          format: uuid
        application:
          type: string
          format: uuid
        organization:
          type: string
          format: uuid
        from_build:
          type: string
          format: uuid
        to_build:
          type: string
          format: uuid
        version_label:
          type: string
        outcome:
          type: string
          enum:
          - success
          - failed
          - rolled_back
      required:
      - installation
      - application
      - to_build
      - outcome
x-moonitoring-consumes:
- event: organization.*.v1, membership.*.v1, organization_role.updated.v1
  producer: access
  why: Evaluates the channel rule with live memberships at every update check.
- event: entitlement.*.v1
  producer: farm
  why: Evaluates required features at every update check.
- event: staff_membership.changed.v1, staff_role.updated.v1
  producer: access
  why: Authorizes the staff audience.
- event: sync_client.enrolled.v1, sync_client.retired.v1
  producer: farm
  why: Links installations of the sync client application to their farm.
- event: erasure_request.executed.v1
  producer: farm
  why: Anonymizes installations and events of the farm's Organization.