Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: fix adeo-kafka-request-reply-asyncapi.yml example #1002

Merged
merged 3 commits into from
Dec 12, 2023

Conversation

smoya
Copy link
Member

@smoya smoya commented Dec 12, 2023

No description provided.

Copy link
Member

@derberg derberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually there are more errors, as v2 adeo tried to workaround last of req/reply, the conversion did not end up very good

final doc should be

asyncapi: 3.0.0
info:
  title: Adeo AsyncAPI Case Study
  version: '%REPLACED_BY_MAVEN%'
  description: >
    This Adeo specification illustrates how ADEO uses AsyncAPI to document some
    of their exchanges.
  contact:
    name: AsyncAPI Community
    email: [email protected]
  tags:
    - name: costing
      description: Costing channels, used by Costing clients.
servers:
  production:
    host: prod.url:9092
    protocol: kafka
    description: Kafka PRODUCTION cluster
    security:
      - $ref: '#/components/securitySchemes/sasl-ssl'
    bindings:
      kafka:
        schemaRegistryUrl: https://schema-registry.prod.url/
  staging:
    host: staging.url:9092
    protocol: kafka
    description: Kafka STAGING cluster for `uat` and `preprod` environments
    security:
      - $ref: '#/components/securitySchemes/sasl-ssl'
    bindings:
      kafka:
        schemaRegistryUrl: https://schema-registry.prod.url/
  dev:
    host: dev.url:9092
    protocol: kafka
    description: Kafka DEV cluster for `dev` and `sit` environments
    security:
      - $ref: '#/components/securitySchemes/sasl-ssl'
    bindings:
      kafka:
        schemaRegistryUrl: https://schema-registry.prod.url/
channels:
  costingRequestChannel:
    address: adeo-{env}-case-study-COSTING-REQUEST-{version}
    description: >
      Use this topic to do a Costing Request to Costing product. We use the
      [**RecordNameStrategy**](https://docs.confluent.io/platform/current/schema-registry/serdes-develop/index.html#subject-name-strategy)
      to infer the messages schema. You have to define
      `value.subject.name.strategy` to
      `io.confluent.kafka.serializers.subject.RecordNameStrategy` in your
      producer to use the schema we manage. The schema below illustrates how
      Costing Request messages are handled.
      ![](https://user-images.githubusercontent.com/5501911/188920831-689cec5f-8dc3-460b-8794-0b54ec8b0ac8.png)
    parameters:
      env:
        $ref: '#/components/parameters/Env'
      version:
        $ref: '#/components/parameters/Version'
    bindings:
      kafka:
        replicas: 3
        partitions: 3
        topicConfiguration:
          cleanup.policy:
            - delete
          retention.ms: 60000000
    messages:
      CostingRequest:
        $ref: '#/components/messages/costingRequestV1'
  costingResponseChannel:
    address: null
    description: >
      This topic is used to REPLY Costing Requests and is targeted by the
      `REPLY_TOPIC` header. **You must grant PUBLISH access to our `svc-ccr-app`
      service account.**. We use the
      [**RecordNameStrategy**](https://docs.confluent.io/platform/current/schema-registry/serdes-develop/index.html#subject-name-strategy)
      to infer the messages schema. 
      
      Topic should follow pattern "adeo-{env}-case-study-COSTING-RESPONSE-{version}"

      You have to define
      `key.subject.name.strategy` and `value.subject.name.strategy` to
      `io.confluent.kafka.serializers.subject.RecordNameStrategy` in your
      consumer. The schema below illustrates how Costing Response messages are
      handled.
           ![](https://user-images.githubusercontent.com/5501911/188920831-689cec5f-8dc3-460b-8794-0b54ec8b0ac8.png)

    bindings:
      kafka:
        x-key.subject.name.strategy:
          type: string
          description: >
            We use the RecordNameStrategy to infer the messages schema. Use
            `key.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
            in your consumer configuration.
        x-value.subject.name.strategy:
          type: string
          description: >
            We use the RecordNameStrategy to infer the messages schema. Use
            `value.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
            in your consumer configuration.
    tags:
      - name: costing
    messages:
      costingResponse:
        $ref: '#/components/messages/costingResponse'
operations:
  receiveACostingRequest:
    action: receive
    channel:
      $ref: '#/channels/costingRequestChannel'
    reply:
      channel:
        $ref: '#/channels/costingResponseChannel'
      address:
        location: $message.header#/REPLY_TOPIC
    summary: |
      [COSTING] Request one or more Costing calculation for any product
    description: >
      You can try a costing request using our [Conduktor producer
      template](https://conduktor.url/)
    tags:
      - name: costing
    bindings:
      kafka:
        groupId:
          type: string
          description: >
            The groupId must be prefixed by your `svc` account, deliver by the
            Adeo Kafka team. This `svc` must have the write access to the topic.
        x-value.subject.name.strategy:
          type: string
          description: >
            We use the RecordNameStrategy to infer the messages schema. Use
            `value.subject.name.strategy=io.confluent.kafka.serializers.subject.RecordNameStrategy`
            in your producer configuration.

components:
  correlationIds:
    costingCorrelationId:
      description: >
        This correlation ID is used for message tracing and messages
        correlation. This correlation ID is generated at runtime based on the
        `REQUEST_ID` and sent to the RESPONSE message.
      location: $message.header#/REQUEST_ID
  messages:
    costingRequestV1:
      name: CostingRequestV1
      title: Costing Request V1
      summary: Costing Request V1 inputs.
      tags:
        - name: costing
      correlationId:
        $ref: '#/components/correlationIds/costingCorrelationId'
      headers:
        type: object
        required:
          - REQUESTER_ID
          - REQUESTER_CODE
          - REQUEST_ID
          - REPLY_TOPIC
        properties:
          REQUEST_ID:
            $ref: '#/components/schemas/RequestId'
          REPLY_TOPIC:
            $ref: '#/components/schemas/ReplyTopic'
          REQUESTER_ID:
            $ref: '#/components/schemas/RequesterId'
          REQUESTER_CODE:
            $ref: '#/components/schemas/RequesterCode'
      payload:
        schemaFormat: application/vnd.apache.avro;version=1.9.0
        schema:
          $ref: https://www.asyncapi.com/resources/casestudies/adeo/CostingRequestPayload.avsc
    costingResponse:
      name: CostingResponse
      title: Costing Response
      summary: Costing Response ouputs.
      tags:
        - name: costing
      description: >
        Please refer to the `CostingResponseKey.avsc` schema, available on [our
        github project](https://github.url/).
      correlationId:
        $ref: '#/components/correlationIds/costingCorrelationId'
      headers:
        type: object
        properties:
          CALCULATION_ID:
            $ref: '#/components/schemas/MessageId'
          CORRELATION_ID:
            $ref: '#/components/schemas/CorrelationId'
          REQUEST_TIMESTAMP:
            type: string
            format: date-time
            description: Timestamp of the costing request
          CALCULATION_TIMESTAMP:
            type: string
            format: date-time
            description: Technical timestamp for the costing calculation
      payload:
        schemaFormat: application/vnd.apache.avro;version=1.9.0
        schema:
          $ref: https://www.asyncapi.com/resources/casestudies/adeo/CostingResponsePayload.avsc
  schemas:
    RequesterId:
      type: string
      description: The Costing requester service account used to produce costing request.
      example: svc-ecollect-app
    RequesterCode:
      type: string
      description: >-
        The Costing requester code (generally the BU Code). The requester code
        is useful to get the dedicated context (tenant).
      example: 1
    MessageId:
      type: string
      format: uuid
      description: A unique Message ID.
      example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef
    RequestId:
      type: string
      format: uuid
      description: >-
        A unique Request ID needed to define a `CORRELATION_ID` for exchanges,
        which will be sent back in the Costing Responses.
      example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef
    CorrelationId:
      type: string
      format: uuid
      description: >-
        A unique Correlation ID defined from the `REQUEST_ID` or the
        `MESSAGE_ID` provided in the Costing Request.
      example: 1fa6ef40-8f47-40a8-8cf6-f8607d0066ef
    BuCode:
      type: string
      description: The Business Unit code for which data are applicable.
      example: 1
    ReplyTopic:
      type: string
      description: >
        The Kafka topic where to send the Costing Response. This is required for
        the [Return Address EIP
        pattern](https://www.enterpriseintegrationpatterns.com/patterns/messaging/ReturnAddress.html).
        **You must grant WRITE access to our `svc-ccr-app` service account.**
      example: adeo-case-study-COSTING-RESPONSE-V1
    ErrorStep:
      type: string
      description: |
        The woker that has thrown the error.
      example: EXPOSE_RESULT
    ErrorMessage:
      type: string
      description: |
        The error message describing the error.
      example: Error message
    ErrorCode:
      type: string
      description: |
        The error code.
      example: CURRENCY_NOT_FOUND
  parameters:
    Env:
      description: Adeo Kafka Environement for messages publications.
      enum:
        - dev
        - sit
        - uat1
        - preprod
        - prod
    Version:
      description: the topic version you want to use
      examples:
        - V1
      default: V1
  securitySchemes:
    sasl-ssl:
      type: plain
      x-sasl.jaas.config: >-
        org.apache.kafka.common.security.plain.PlainLoginModule required
        username="<CLUSTER_API_KEY>" password="<CLUSTER_API_SECRET>";
      x-security.protocol: SASL_SSL
      x-ssl.endpoint.identification.algorithm: https
      x-sasl.mechanism: PLAIN
      description: >
        Use [SASL authentication with SSL
        encryption](https://docs.confluent.io/platform/current/security/security_tutorial.html#configure-clients)
        to connect to the ADEO Broker.

@smoya
Copy link
Member Author

smoya commented Dec 12, 2023

please @derberg , can you share the diff? I fixed the URLs to not point to preview just in case that was the remaining issue

@smoya
Copy link
Member Author

smoya commented Dec 12, 2023

Ok, I see you changed tons of other things. Adding your version then @derberg

@smoya smoya marked this pull request as ready for review December 12, 2023 11:14
Copy link

Kudos, SonarCloud Quality Gate passed!    Quality Gate passed

Bug A 0 Bugs
Vulnerability A 0 Vulnerabilities
Security Hotspot A 0 Security Hotspots
Code Smell A 0 Code Smells

No Coverage information No Coverage information
0.0% 0.0% Duplication

@smoya
Copy link
Member Author

smoya commented Dec 12, 2023

Updated @derberg

Copy link
Member

@derberg derberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@smoya the most notable change is:

line 71, so set address of costingResponseChannel channel to null as it is response channel, dynamic way when respons channel is passed in a header

and I removed getCostingResponse operation, as there is no send operation there, there is only receive and reply and if something is just a reply, it do not need to have separate send as it is not a typical send operation but a reply to receive here


the rest is editorial I took from @M3lkior

@smoya
Copy link
Member Author

smoya commented Dec 12, 2023

/rtm

@asyncapi-bot asyncapi-bot merged commit 6c6d527 into asyncapi:master Dec 12, 2023
16 checks passed
@smoya smoya deleted the chore/fixExample branch December 12, 2023 11:22
retention.ms: 604800000
cleanup.policy:
- delete
retention.ms: 60000000
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
retention.ms: 60000000
retention.ms: 604800000

Comment on lines -242 to -245
bindings:
kafka:
key:
$ref: "https://deploy-preview-921--asyncapi-website.netlify.app/resources/casestudies/adeo/CostingResponseKey.avsc"
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this part need to be kept

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Feel free to open a new PR.
I had to merge asap because CLI was affected, we don't know if other tools as well. The fix for that is also a wip so it doesnt happen again.

@asyncapi-bot
Copy link
Contributor

🎉 This PR is included in version 3.0.1 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants