asyncapi-archived-repos / cupid Goto Github PK

Output Diagram for flight Service.

for PlantUML

Unfortunately, reactFlow have a problem of overlapping edges as we can see in the diagram above, when we compare it to the plantUML diagram it shows, we need the flight/update label shown on an edge going from Flight Monitor Service to the server.

Solution: Implement custom edge Component: xyflow/xyflow#819 (comment)

Reason/Context

In the new version of AsyncAPI 2.2.0 you are allowed to define which servers a channel is designated towards. This is instead of using the default behavior of being related towards all defined servers.

Example AsyncAPI document:

asyncapi: 2.2.0
info:
  title: Website Backend
  version: 1.0.0
servers:
  websiteWebSocketServer:
    url: ws://mycompany.com/ws
    protocol: ws
  mosquitto:
    url: mqtt://test.mosquitto.org
    protocol: mqtt
    bindings:
      mqtt:
        clientId: websocketServer
channels:
  comment/liked:
    description: Notify all the services that a comment has been liked.
    servers: ['mosquitto']
    subscribe: 
      message:
        payload: true
  like/comment:
    description: When a comment like is received from the frontend.
    servers: ['websiteWebSocketServer']
    publish: 
      message:
        payload: true

In this example I would expect that like/comment is only related to the websiteWebSocketServer and comment/liked towards mosquitto.

Describe the bug

Based on this: #67 (comment)

I tried to pre-parse my AsyncAPI documents and then give Cupid those pre-parsed documents as inputs.

How to Reproduce

Follow #67 (comment) example.

Expected behavior

By changing the validation function: https://github.com/asyncapi/cupid/blob/c9cdb3df6675d992a42ccbd9e92bd118a21a11d4/lib/utils.js#L9

To something like the following everything works:

function validate(asyncApiDocs) {
  return Promise.all(asyncApiDocs.map(async doc => {
    if (typeof doc === 'object' && doc.ext && doc.ext('x-parser-spec-parsed')) {
      return doc;
    }
    return parser.parse(doc);
  }));
}

This is because the provided document does not have a property called x-parser-spec-parsed in the root object, it is hidden under _json, so it would be an idea to use the functions to access the extension 🙂

We use slug to map relations with different servers described in the asyncAPI document.

 slug = `${credentials.url()},${credentials.protocol()}`;

What if user described server's url with parameters like server/{parameter} and define for this parameter some enum values. With the current flow we would be mapping server/{parameter} as it is.

This might be a big concern and, we have to configure the flow to support this case too.

Reason/Context

This Issue is used to track changes needed to support AsyncAPI v3. As a code owner, please edit this list of TODO tasks in order to properly track the progress 🙂 Once this issue is closed it means that v3 is now fully supported in this library.

Remaining tasks:

• Update to parser v2
• Once asyncapi/parser-js#780 is solved, update parser dependency (might be automated)

At the moment user can use getRelations function and pass options which format he/she needs, but we can change this behaviour and always return default syntax and then export from package the getMermaidDiagram function, so usage of package will look like:

const output = appRelationsDiscovery.getRelations(...asyncAPIDocs);
const mermaid = appRelationsDiscovery.getMermaidDiagram(output);

When we will support class models for our metrics we could have APIs which could add a subscriber or publisher to the channel to see what happens with the system if one of the puzzles is removed/added.

const output = appRelationsDiscovery.getRelations(...asyncAPIDocs);
output.subscribe(<channelName>,<server>,<serviceName>);
const mermaid = appRelationsDiscovery.getMermaidDiagram(output);

app-relations-discovery is a self-descriptive name in itself, no doubt about that. But can we have a name which is short and more quick to speak.

My proposition is more vivid and short like web which would then goes by the npm package @asyncapi/web signifying the connection between the AsyncApi docs => 🕸️ spider web xD
Any more ideas?

Currently, we have hardcoded the animation option in the elements array for reactFlow:

const edge = { id: `edge${edgId}`, source: `${service}`, target: `Server${i}`, animated: true, label: `${channel}`, type: 'edgeType', arrowHeadType: 'arrowclosed'};

We should have it configurable , so user should have possibility to pass related config object to the given metrics.

cc: @magicmatatjahu

Reason/Context

Would be awesome to build a library that as the input gets an array of AsyncAPI documents and analyzes them to get information about Applications described by those files:

• If they subscribe or publish to the same channels
• If one subscribes to a channel that the other one publishes to
• If there are apps that are subscribed to channels that no one publishes too

As an output, we should get a format that can be used to generate a diagram of relations between applications with additional metadata information about them (message, schemas).

Use case:

Visualization of the architecture and understanding what happens with the system if one of the puzzles is removed.
Later on, we could use this library in AsyncAPI CLI and also the AsyncAPI Studio.

Required knowledge:
There is no need to have any experience in event-driven architecture. You do not even need to know AsyncAPI spec too much. It is a pure coding task where you will need to find matching patterns between different documents and return this information. This should be an independent library that can be later reused in AsyncAPI CLI or AsyncAPI Studio, or by others in their tools.

Description

• you do not have to implement any reading of AsyncAPI files from disk or URL or anything like this. It is a library and its API should accept an array of AsyncAPI documents and these can be already after being parsed by https://github.com/asyncapi/parser-js/
• biggest unknow is the output, what would be the best format to choose here as an output. Should it follow syntax from mermaid or maybe we need something custom? I think it would be better to first try to "manually" try to get 2 asyncapi docs, identify relations between them and then model the output "manually" to get an idea how it should be structured, maybe we need pure uml output? 🤷🏼

I will be stepping down as maintainer for this repo.

@arjungarg07 afaik from different discussions you also cannot longer work on this repo

@magicmatatjahu I believe you also have different responsibilities

My proposal:

• Rename this but to "Looking for new maintainers"
• Pin this issue so it is visible to anyone looking into Issues tab
• Add note in readme that we are looking for maintainers
• Create a discussion in community that this project will be archived in 1 month unless someone is interested to take this over and maintain forward
  • must have at least 2 new maintainers
  • maintainers should have some company support or at least provide a proof that they use the project or have a use case for it, therefore they have interest in maintaining the project long term. Basically make sure that we do not get just students volunteers that would treat this project as path to TSC. We basically need experience folks with use cases that can drive project forward independently
• Ask Thulie to share discussion on AsyncAPI social media and newsletter so potential users of cupid know about it. At the moment we are getting only 24 weekly downloads

After a month from publishing the discussion in social media, if there is noone to take over, we will archive repo and move to https://github.com/asyncapi-archived-repos

Thoughts?

• generate API docs instead of manual maintainance. Have a look at JS Parser and how we do it there https://github.com/asyncapi/parser-js/blob/master/package.json#L13
• extend readme with example usage of the library
• present every single diagram syntax and example output screen shot
• in case of react flow explain all steps that user needs to perform to get a final diagram rendered
• explain in technical details how the relations are discovered, basing on what information
• explain and present the default output of the library, what is in the output map, what info is available (can be just well annotated with jsdoc in the code and later generated in API doc)

What Dev Docs changes are you proposing?

It is not possible to know what the DiscoveredRelations type is. Which makes it hard to use the default relationship finder.

Code of Conduct

• I agree to follow this project's Code of Conduct

Having separate classes that imply the metrics map structure could potentially improve the scope of the library because we could add multiple types of APIs.

Describe the bug

If you use an AsyncAPI document with multiple channels, it renders all of the channels on top of each other.

How to Reproduce

Given an AsyncAPI document with 2 channels, it will generate the following elements:

export default function ServiceOverview() {
  const asd1 = [
    {
      id: 'Server1',
      data: { label: 'test.nats.org:{port},nats' },
      position: { x: 250, y: 5 }
    },
    {
      id: 'Rustserver',
      data: { label: 'Rust server' },
      position: { x: 100, y: 10 }
    },
    {
      id: 'edge1',
      source: 'Rustserver',
      target: 'Server1',
      animated: true,
      label: 'v0/rust/servers/{server_id}/events/wiped',
      type: 'edgeType',
      arrowHeadType: 'arrowclosed'
    },
    {
      id: 'edge2',
      source: 'Rustserver',
      target: 'Server1',
      animated: true,
      label: 'v0/rust/servers/{server_id}/events/started',
      type: 'edgeType',
      arrowHeadType: 'arrowclosed'
    }
  ]
  
  return (
      <div style={{ height: 300 }}>
        <ReactFlow elements={asd1} />
      </div>
  )
}

Will render all channels as:

Expected behavior

Expected all channels to be visible.

This issue defines a list of tasks that need to be performed in this repo to make sure it's ci/cd automation works long term without any issues.

It is up to maintainers to decide if it must be addressed in one or multiple PRs.

Below are 3 different sections describing 3 different important ci/cd changes.

IMPORTANT-START
For GitHub workflows that contain This workflow is centrally managed in https://github.com/asyncapi/.github/ you do not have to perform any work. These workflows were already updated through the update in .github. The only exception is the workflows related to nodejs release. More details in Upgrade Release pipeline - in case of nodejs projects section
IMPORTANT-END

Deprecation of way data is shared between steps

Every single GitHub Action workflow that has echo "::set-output name={name}::{value}" need to be updated to follow echo "{name}={value}" >> $GITHUB_OUTPUT

We do not yet know when set-output will stop working. Previous disable date was 31.05 but now then say community needs more time.

For more details read official article from GitHub

Deprecation of node12

2nd bullet point is still relevant for you even if your projects in not nodejs project

• Every single workflow that uses setup-node action needs an update to follow v3 version of this action, and make sure minimum node 14 is used
• Now this part is more complex. Problem with node12 is that node-based GitHub Actions were using it in majority as a runtime environment. Look for example at this action.yaml file for setup-node action v2. So the job that you have to do is go through all the workflows, and verify every single action that you use, make sure you are using the latest version that is not based on node12. I already did review a lot of actions as part of this PR so maybe you will find some actions there and can copy from me. For example action/checkout needs to be updated to v3.

Node12 end of support in action is probably September 27th.

For more details read official article from GitHub

Upgrade Release pipeline - in case of nodejs projects

ignore this section if your project is not nodejs project

You have 2 options. You can:

A. choose to switch to new release pipeline using instruction from asyncapi/.github#205

B. stay with old release pipeline, and manually update GitHub workflows and actions used in it, you can inspire a lot from this PR asyncapi/.github#226

I definitely recommend going with A

Workflows related to release:

• .github/workflows/if-nodejs-release.yml
• .github/workflows/if-nodejs-version-bump.yml
• .github/workflows/bump.yml

Describe the bug

If you try to use the library with an AsyncAPI file that uses relative references and you are not in the same directory (when running the library) it will fail to fetch the correct file.

How to Reproduce

If your setup is:

• cupid
  • index.js
• asyncapi.yaml
• dictionary.yaml

Where asyncapi.yaml reference the dictionary.yaml, using a relative reference such as ./dictionary.yaml the library throws an error that the file cannot be found because it tries to look for it here: cupid/dictionary.yaml.

asyncapi.yaml file:

asyncapi: 2.2.0
info:
  title: Website Backend
  version: 1.0.0
channels:
  comment/liked:
    description: Notify all the services that a comment has been liked.
    subscribe: 
      message:
        $ref: './dictionary.yaml#/components/messages/commentLiked'

dictionary.yaml file:

components:
  messages:
    commentLiked: 
      payload: 
        $ref: '#/components/schemas/commentLikedPayload'
  schemas: 
    commentLikedPayload: 
      type: object
      title: commentLikedPayload
      additionalProperties: false
      properties:
        commentId: 
          allOf: 
            - $ref: '#/components/schemas/commentId'
            - description: Id of the comment that was liked
    commentId:
      type: string

Expected behavior

Expected when the asyncapi.yaml file is parsed, that it is parsed from it's base directory.

We should add this amazing tool to https://www.asyncapi.com/docs/community/tooling :)

More details - https://sonarcloud.io/project/issues?id=asyncapi_app-relations-discovery&issues=AXqGZiF-YcU7Bh3YkME2&open=AXqGZiF-YcU7Bh3YkME2

code from lib/appRelationsDiscovery.js

Reason/Context

Triggered by #67 (comment), as we currently have no way to pass options to the parser that Cupid uses. Meaning everyone needs to pre-parse their documents beforehand for references to be accurately dereferenced.

We can remove such needs by supporting file inputs (or a way to pass options to the parser 🧐).

more details:

• https://sonarcloud.io/project/issues?id=asyncapi_app-relations-discovery&issues=AXqGZiF-YcU7Bh3YkME4&open=AXqGZiF-YcU7Bh3YkME4
• https://sonarcloud.io/project/issues?id=asyncapi_app-relations-discovery&issues=AXqGZiF-YcU7Bh3YkME3&open=AXqGZiF-YcU7Bh3YkME3

Reason/Context

This is to replace the old AsyncAPI logo in this repo's README with the banner attached below that represents the new branding.

Here are a few guidelines for this change as well:

1. Make sure you are using Markdown syntax only
2. Be sure to remove the old logo as well as the old title of the repo as this image will replace both elements
3. Make sure you link this image to the website: https://www.asyncapi.com
4. If there is any description text below the repo title, let's make it left-aligned if it isn't already, so as to match the left-alignment of the content in the new banner image

Download the image file:
github-repobanner-cupid.png.zip

Banner preview

Please note that this is only a preview of the image, the contributor should download and use the above zip file

Describe the bug

Cupid creates a non-usable mermaid diagram when an AsyncAPI file has a channel using parameters.

How to Reproduce

Given the following file, it generates an unusable mermaid diagram:

asyncapi: 2.2.0
info:
  title: Comments Service
  version: 1.0.0
  description: This service is in charge of processing all the events related to comments.
servers:
  mosquitto:
    url: mqtt://test.mosquitto.org
    protocol: mqtt
    bindings:
      mqtt:
        clientId: comment-service
channels:
  comment/{commentId}/changed:
    description: Sends the new count to the broker after it has been updated in the database.
    parameters: 
      commentId:
        schema: 
          type: string
    subscribe: 
      message:
        payload: true

Which gives the output:

graph TD
 server1[(mqtt://test.mosquitto.org)]
CommentsService -- comment/{commentId}/changed --> server1

Expected behavior

Expected mermaid diagram channels to be wrapped with ".

graph TD
 server1[(mqtt://test.mosquitto.org)]
CommentsService -- "comment/{commentId}/changed" --> server1

Describe the bug

The usage example for node cannot be used as is, as the generation of the relationships is asynchronous and does not return the result but a promise.

I had to adapt it to:

const cupid = require('@asyncapi/cupid');
const path = require('path');
const fs = require('fs');

async function getAsyncApiExamples() {
  const docs = [];
  const files = [
    ..
  ]
  for (const file of files) {
    const asyncApiDoc = fs.readFileSync(file, 'utf8');
    docs.push(asyncApiDoc);
  }
  try {
    const mermaidFlowchart = await cupid.getRelations(docs,{syntax:'mermaid'});
    console.log(mermaidFlowchart);
  } catch (error) {
    console.error(error);
  }
}
getAsyncApiExamples();

How to Reproduce

Use the example code as-is.

Expected behavior

That the example works as is without any changes.