Swagger updates

[alonp99]

User description

Description

Elaborate on the subject, motivation, and context.

Related issues

• Provide a link to each related issue.

Breaking changes

• Describe the breaking changes that this pull request introduces.

How these changes were tested

• Describe the tests that you ran to verify your changes, including devices, operating systems, browsers and versions.

Examples and references

• Links, screenshots, and other resources related to this change.

Checklist

• [] I have read the contribution guidelines of this project
• [] I have read the style guidelines of this project
• [] I have performed a self-review of my own code
• [] I have commented my code, particularly in hard-to-understand areas
• [] I have made corresponding changes to the documentation
• [] My changes generate no new warnings and errors
• [] New and existing tests pass locally with my changes

---

Type

enhancement, documentation

---

Description

• Introduced a detailed schema for webhook notifications in swagger.ts, including event details, workflow information, and additional data specific to workflow type.
• Added HMAC signature authentication details for webhook payload integrity and authenticity.
• Enhanced documentation for WorkflowRunDto properties with descriptions and examples.
• Provided a detailed API operation summary and body examples for the /run endpoint, explaining the process to initiate and execute workflows.
• Updated the data migration subproject commit reference.

---

Changes walkthrough

	Relevant files
Enhancement	swagger.ts Comprehensive Update to Webhook Notifications Schema and Security services/workflows-service/src/swagger/swagger.ts Expanded the requestBody description for workflow events with detailed information on webhook notifications. Introduced a comprehensive schema for webhook payload including event details, workflow information, and additional data specific to workflow type. Added security section with HMAC signature authentication details for webhook payload integrity and authenticity. +643/-2
Documentation	workflow-run.ts Enhanced Documentation for Workflow Run DTO Properties      services/workflows-service/src/workflow/dtos/workflow-run.ts Added detailed descriptions and examples for workflowId, context, and config properties in WorkflowRunDto. +35/-4    workflow.controller.external.ts Detailed API Documentation for Workflow Execution Endpoint services/workflows-service/src/workflow/workflow.controller.external.ts Added detailed API operation summary and body examples for the /run endpoint. Described the process to initiate and execute workflows with examples. +48/-0
Configuration changes	data-migrations Data Migration Subproject Commit Update                                    services/workflows-service/prisma/data-migrations Updated the data migration subproject commit reference. +1/-1

---

✨ PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[changeset-bot[bot]]

⚠️ No Changeset found

Latest commit: 0713253e5a1fcbfe907c96dddb4946957555d6f3

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[github-actions[bot]]

PR Description updated to latest commit (https://github.com/ballerine-io/ballerine/commit/4f5f1707af8bef2eb56c6372fbdd9c98fb107621)

[github-actions[bot]]

PR Review

⏱️ Estimated effort to review [1-5]	4, due to the extensive changes in the webhook schema, the introduction of HMAC authentication, and the detailed documentation updates. The complexity and volume of the changes require a thorough review to ensure accuracy, security, and adherence to best practices.
🧪 Relevant tests	No
🔍 Possible issues	Possible Bug: The nullable: true properties in the webhook schema might lead to unexpected behavior or errors if not handled properly in the consuming code. Ensure that all parts of the application that consume this data can handle null values gracefully.
	Performance Concern: The detailed webhook schema with numerous nested objects and properties could impact the performance of serialization and deserialization processes, especially under high load. Consider benchmarking these operations to identify potential bottlenecks.
🔒 Security concerns	HMAC Implementation: While the addition of HMAC signature authentication is a positive step for security, it's crucial to ensure that the implementation is secure against timing attacks. Verify that the comparison of the computed HMAC signature to the received signature is done in constant time to prevent timing attacks.

Code feedback:

---

relevant file	services/workflows-service/src/swagger/swagger.ts
suggestion	Consider adding enum or const definitions for the repeated string values such as workflow event names and risk levels. This can reduce the risk of typos and make the codebase easier to maintain. [important]
relevant line	description: 'Name of the workflow event.',

---

relevant file	services/workflows-service/src/swagger/swagger.ts
suggestion	For properties that have a nullable: true attribute, ensure that the consuming code checks for null values to avoid runtime errors. This is particularly important for deeply nested properties. [important]
relevant line	nullable: true,

---

relevant file	services/workflows-service/src/workflow/dtos/workflow-run.ts
suggestion	Add validation decorators for the nested properties within the context object to ensure that the input data conforms to expected formats and types. This can help prevent invalid data from being processed. [medium]
relevant line	example: {

---

relevant file	services/workflows-service/src/workflow/workflow.controller.external.ts
suggestion	Ensure that the API documentation accurately reflects all possible HTTP status codes that the endpoint can return, including error codes. This helps consumers of the API to handle responses more effectively. [medium]
relevant line	@swagger.ApiOperation({

---

---

✨ Review tool usage guide:

---

Overview: The review tool scans the PR code changes, and generates a PR review. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on any PR. When commenting, to edit configurations related to the review tool (pr_reviewer section), use the following template:

/review --pr_reviewer.some_config1=... --pr_reviewer.some_config2=...

With a configuration file, use the following template:

[pr_reviewer]
some_config1=...
some_config2=...

Utilizing extra instructions The review tool can be configured with extra instructions, which can be used to guide the model to a feedback tailored to the needs of your project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify the relevant sub-tool, and the relevant aspects of the PR that you want to emphasize. Examples for extra instructions: [pr_reviewer] # /review # extra_instructions=""" In the 'possible issues' section, emphasize the following: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

How to enable\disable automation When you first install PR-Agent app, the default mode for the review tool is: pr_commands = ["/review", ...] meaning the review tool will run automatically on every PR, with the default configuration. Edit this field to enable/disable the tool, or to change the used configurations

Auto-labels The review tool can auto-generate two specific types of labels for a PR: a possible security issue label, that detects possible security issues (enable_review_labels_security flag) a Review effort [1-5]: x label, where x is the estimated effort to review the PR (enable_review_labels_effort flag)

Extra sub-tools The review tool provides a collection of possible feedbacks about a PR. It is recommended to review the possible options, and choose the ones relevant for your use case. Some of the feature that are disabled by default are quite useful, and should be considered for enabling. For example: require_score_review, require_soc2_ticket, require_can_be_split_review, and more.

Auto-approve PRs By invoking: /review auto_approve The tool will automatically approve the PR, and add a comment with the approval. To ensure safety, the auto-approval feature is disabled by default. To enable auto-approval, you need to actively set in a pre-defined configuration file the following: [pr_reviewer] enable_auto_approval = true (this specific flag cannot be set with a command line argument, only in the configuration file, committed to the repository) You can also enable auto-approval only if the PR meets certain requirements, such as that the estimated_review_effort is equal or below a certain threshold, by adjusting the flag: [pr_reviewer] maximal_review_effort = 5

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the review usage page for a comprehensive guide on using this tool.

[github-actions[bot]]

PR Code Suggestions

Category	Suggestions
Maintainability	Break down the lengthy description into a concise summary and detailed descriptions within properties. Consider breaking down the lengthy description into a more concise summary and detailed descriptions within each property. This approach enhances readability and maintainability. services/workflows-service/src/swagger/swagger.ts [78] -description: - 'Webhooks notify clients about workflow events asynchronously. Events include creation, start, completion, failure, and context updates of workflows. Webhook payloads contain information like event ID, name, API version, timestamps, workflow IDs, status, final state, Ballerine entity ID, correlation ID, and environment. Additional data varies by workflow type and checks. Clients must configure an endpoint to receive POST requests with webhook notifications and verify requests using HMAC signatures for security.' +description: 'Webhooks notify clients about workflow events asynchronously.' +additionalDetails: 'Events include creation, start, completion, failure, and context updates. Payloads contain event ID, name, API version, timestamps, workflow IDs, status, final state, Ballerine entity ID, correlation ID, environment, and more. Clients must configure an endpoint to receive POST requests and verify requests using HMAC signatures for security.'
Best practice	Explicitly mark nullable properties in the schema to ensure data integrity. To ensure data integrity and prevent potential issues, consider marking the nullable properties explicitly in the schema for properties like indicator, instagram, websiteStructureEvaluation, trafficAnalysis, transactionAnalysis, and others where nullable: true is used. services/workflows-service/src/swagger/swagger.ts [208-217] indicator: { type: 'object', nullable: true, properties: { riskLevel: { type: 'string', + nullable: true, }, name: { type: 'string', + nullable: true, }, }, },
	Define enum properties as TypeScript enum types for better reusability and maintainability. For the enum property eventName, consider defining it as a TypeScript enum type outside of the Swagger schema and then referencing it. This approach promotes code reusability and maintainability. services/workflows-service/src/swagger/swagger.ts [88-101] +enum EventName { + WorkflowCompleted = 'workflow.completed', + WorkflowStateChanged = 'workflow.state.changed', + WorkflowContextChanged = 'workflow.context.changed', + WorkflowCreated = 'workflow.created', + WorkflowResolved = 'workflow.resolved', + WorkflowStarted = 'workflow.started', + WorkflowFailed = 'workflow.failed', + WorkflowResumed = 'workflow.resumed', + WorkflowCancelled = 'workflow.cancelled', +} + eventName: { type: 'string', description: 'Name of the workflow event.', - enum: [ - 'workflow.completed', - 'workflow.state.changed', - 'workflow.context.changed', - 'workflow.created', - 'workflow.resolved', - 'workflow.started', - 'workflow.failed', - 'workflow.resumed', - 'workflow.cancelled', - ], - example: 'workflow.completed', + enum: EventName, + example: EventName.WorkflowCompleted, },
	Use a more specific type or class for the context property for better type safety and validation. For better type safety and validation, consider using a more specific type or class for the context property instead of DefaultContextSchema. This can help ensure that the data structure for the context is correctly followed. services/workflows-service/src/workflow/dtos/workflow-run.ts [17-48] +class WorkflowContext extends DefaultContextSchema { + // Define specific properties for the workflow context here +} + @ApiProperty({ required: true, - type: 'object', + type: WorkflowContext, description: 'The context data required by the workflow.', example: { value: { workflowId: '5f8d8e8b8c8d8e8b8c8d8e8b', context: { entity: { type: 'business', id: '123456', data: {}, }, documents: [ { category: 'businessRegistration', type: 'certificateOfIncorporation', issuer: { country: 'US', }, pages: [ { ballerineFileId: 'file123', }, ], properties: {}, }, ], }, }, }, })
Enhancement	Add decorators to document common error scenarios for the /run endpoint. To improve the API documentation and user experience, consider adding @swagger.ApiBadRequestResponse and @swagger.ApiInternalServerErrorResponse decorators to handle and document common error scenarios for the /run endpoint. services/workflows-service/src/workflow/workflow.controller.external.ts [145] @swagger.ApiForbiddenResponse({ type: errors.ForbiddenException }) [email protected]({ description: 'Invalid request parameters.' }) [email protected]({ description: 'Internal server error.' })

---

✨ Improve tool usage guide:

---

Overview: The improve tool scans the PR code changes, and automatically generates suggestions for improving the PR code. The tool can be triggered automatically every time a new PR is opened, or can be invoked manually by commenting on a PR. When commenting, to edit configurations related to the improve tool (pr_code_suggestions section), use the following template:

/improve --pr_code_suggestions.some_config1=... --pr_code_suggestions.some_config2=...

With a configuration file, use the following template:

[pr_code_suggestions]
some_config1=...
some_config2=...

Enabling\disabling automation When you first install the app, the default mode for the improve tool is: pr_commands = ["/improve --pr_code_suggestions.summarize=true", ...] meaning the improve tool will run automatically on every PR, with summarization enabled. Delete this line to disable the tool from running automatically.

Utilizing extra instructions Extra instructions are very important for the improve tool, since they enable to guide the model to suggestions that are more relevant to the specific needs of the project. Be specific, clear, and concise in the instructions. With extra instructions, you are the prompter. Specify relevant aspects that you want the model to focus on. Examples for extra instructions: [pr_code_suggestions] # /improve # extra_instructions=""" Emphasize the following aspects: - Does the code logic cover relevant edge cases? - Is the code logic clear and easy to understand? - Is the code logic efficient? ... """ Use triple quotes to write multi-line instructions. Use bullet points to make the instructions more readable.

A note on code suggestions quality While the current AI for code is getting better and better (GPT-4), it's not flawless. Not all the suggestions will be perfect, and a user should not accept all of them automatically. Suggestions are not meant to be simplistic. Instead, they aim to give deep feedback and raise questions, ideas and thoughts to the user, who can then use his judgment, experience, and understanding of the code base. Recommended to use the 'extra_instructions' field to guide the model to suggestions that are more relevant to the specific needs of the project, or use the custom suggestions :gem: tool With large PRs, best quality will be obtained by using 'improve --extended' mode.

More PR-Agent commands To invoke the PR-Agent, add a comment using one of the following commands: /review: Request a review of your Pull Request. /describe: Update the PR title and description based on the contents of the PR. /improve [--extended]: Suggest code improvements. Extended mode provides a higher quality feedback. /ask <QUESTION>: Ask a question about the PR. /update_changelog: Update the changelog based on the PR's contents. /add_docs 💎: Generate docstring for new components introduced in the PR. /generate_labels 💎: Generate labels for the PR based on the PR's contents. /analyze 💎: Automatically analyzes the PR, and presents changes walkthrough for each component. See the tools guide for more details. To list the possible configuration parameters, add a /config comment.

See the improve usage page for a more comprehensive guide on using this tool.

[coderabbitai[bot]]

Walkthrough

The recent updates enhance the workflows-service by refining webhook notification schemas, adding security measures, and improving data validation and documentation. Key changes include expanded webhook payload details, HMAC signature authentication, and enriched API property descriptions and examples, ensuring clearer and more secure data handling.

Changes

Files	Change Summary
services/workflows-service/prisma/data-migrations	Updated subproject commit from 618d172b5030221a03986ada2b4d0beda231a489 to 8e4db189152411e938454e8a8dceca3ee1c50352.
services/workflows-service/src/swagger/swagger.ts	Enhanced requestBody schema and description in SwaggerSingleton class for webhook notifications, added security field for HMAC authentication.
services/workflows-service/src/workflow/dtos/workflow-run.ts	Added validation decorators and expanded API property descriptions and examples for workflowId and context properties in WorkflowRunDto class.
services/workflows-service/src/workflow/workflow.controller.external.ts	Detailed description added to @swagger.ApiOperation for /run endpoint and example added to @swagger.ApiBody annotation for WorkflowRunDto in createWorkflowRuntimeData method.

🐇 In the code where workflows live, More details and security we now give. With HMAC and schemas bright, Our payloads are now a delight. Validations strong, examples clear, The future of workflows is here! 🛠️✨

---

Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media?

Share

• X
• Mastodon
• Reddit
• LinkedIn

Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>.
  • Generate unit testing code for this file.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai generate unit testing code for this file.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai generate interesting stats about this repository and render them as a table.
  • @coderabbitai show all the console.log statements in this repository.
  • @coderabbitai read src/utils.ts and generate unit testing code.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (invoked as PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger a review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai help to get help.

Additionally, you can add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.

CodeRabbit Configration File (.coderabbit.yaml)

• You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
• Please see the configuration documentation for more information.
• If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.