messageflow

README

MessageFlow

MessageFlow is a Go library and CLI tool for visualizing AsyncAPI specifications. It provides tools to parse AsyncAPI documents and transform them into visual formats, making it easier to understand message flows and service interactions in asynchronous systems.

Example of visualizing a Notification service using this AsyncAPI specification. It can be useful to display service communication with a message bus without requiring detailed knowledge about other services in the ecosystem. Message payloads are displayed as thumbnails when hovering over specific queues. This approach was chosen to keep the schema clean and uncluttered.

When you have AsyncAPI specifications for all services in your system, MessageFlow can generate comprehensive documentation showing the complete service ecosystem. See examples/docs for a complete multi-service documentation example. For instance, in the generated documentation, the same service now appears like this:

Usage

MessageFlow provides a command-line interface.

go install github.com/denchenko/messageflow/cmd/messageflow@latest

Generate Schema

The gen-schema command processes AsyncAPI files and generates formatted schemas or rendered diagrams:

# Generate and render a diagram
messageflow gen-schema --target d2 --render-to-file schema.svg --asyncapi-files asyncapi.yaml

# Generate formatted schema only
messageflow gen-schema --format-to-file schema.d2 --asyncapi-files asyncapi.yaml

# Process multiple AsyncAPI files
messageflow gen-schema --render-to-file combined.svg --asyncapi-files "file1.yaml,file2.yaml,file3.yaml"

Generate Documentation

The gen-docs command generates comprehensive markdown documentation from AsyncAPI files, including diagrams and changelog tracking:

# Generate documentation for multiple services
messageflow gen-docs --asyncapi-files "service1.yaml,service2.yaml,service3.yaml" --output ./docs

The generated documentation includes:

• Context diagram: Overview of all services and their interactions
• Service diagrams: Individual diagrams showing each service's channels and operations
• Channel diagrams: Detailed views of message flows through specific channels
• Changelog tracking: Automatic detection and documentation of schema changes between runs
• Message payloads: JSON schemas for all message types

Documentation

Overview

Package messageflow provides tools for visualizing AsyncAPI specifications. It enables parsing AsyncAPI documents and transforming them into visual format to help understand message flows and service interactions.

Index

• Constants
• func NewUnsupportedFormatError(given, expected TargetType) error
• func NewUnsupportedFormatModeError(given FormatMode, expected []FormatMode) error
• type Action
• type Change
• type ChangeType
• type Changelog
  • func CompareSchemas(oldSchema, newSchema Schema) Changelog
• type Channel
• type FormatMode
• type FormatOptions
• type FormattedSchema
• type Message
• type Operation
• type Schema
  • func MergeSchemas(schemas ...Schema) Schema
  • func (s *Schema) Sort()
• type SchemaExtractor
• type SchemaFormatter
• type SchemaRenderer
• type Service
• type Source
• type Target
• type TargetCapabilities
• type TargetType
• type UnsupportedFormatError
  • func (err *UnsupportedFormatError) Error() string
• type UnsupportedFormatModeError
  • func (err *UnsupportedFormatModeError) Error() string

Constants

const (
	FormatModeContextServices = FormatMode("context_services")
	FormatModeServiceChannels = FormatMode("service_channels")
	FormatModeChannelServices = FormatMode("channel_services")
	FormatModeServiceServices = FormatMode("service_services")
)

Functions

func NewUnsupportedFormatError

func NewUnsupportedFormatError(given, expected TargetType) error

NewUnsupportedFormatError creates a new UnsupportedFormatError.

func NewUnsupportedFormatModeError

func NewUnsupportedFormatModeError(given FormatMode, expected []FormatMode) error

NewUnsupportedFormatModeError creates a new UnsupportedFormatModeError.

Types

type Action

type Action string

Action represents the type of operation that can be performed on a channel.

const (
	ActionSend    Action = "send"
	ActionReceive Action = "receive"
)

type Change

type Change struct {
	Type      ChangeType `json:"type"`
	Category  string     `json:"category"`
	Name      string     `json:"name"`
	Details   string     `json:"details,omitempty"`
	Diff      string     `json:"diff,omitempty"`
	Timestamp time.Time  `json:"timestamp"`
}

Change represents a single change in the schema.

type ChangeType

type ChangeType string

ChangeType represents the type of change that occurred.

const (
	ChangeTypeAdded   ChangeType = "added"
	ChangeTypeRemoved ChangeType = "removed"
	ChangeTypeChanged ChangeType = "changed"
)

type Changelog

type Changelog struct {
	Date    time.Time `json:"date"`
	Changes []Change  `json:"changes"`
}

Changelog represents a collection of changes with a version and date.

func CompareSchemas

func CompareSchemas(oldSchema, newSchema Schema) Changelog

CompareSchemas compares two schemas and returns a changelog of differences.

type Channel

type Channel struct {
	Name    string  `json:"name"`
	Message Message `json:"message"`
}

Channel represents a communication channel with a name and message.

type FormatMode

type FormatMode string

FormatMode represents the mode of format for schema.

type FormatOptions

type FormatOptions struct {
	Mode         FormatMode
	Service      string
	Channel      string
	OmitPayloads bool
}

type FormattedSchema

type FormattedSchema struct {
	Type TargetType `json:"type"`
	Data []byte     `json:"data"`
}

FormattedSchema represents a schema that has been formatted for a specific target type.

type Message

type Message struct {
	Name    string `json:"name"`
	Payload string `json:"payload"`
}

Message represents a message with a name and payload.

type Operation

type Operation struct {
	Action  Action   `json:"action"`
	Channel Channel  `json:"channel"`
	Reply   *Channel `json:"reply,omitempty"`
}

Operation defines an action to be performed on a channel, optionally with a reply channel.

type Schema

type Schema struct {
	Services []Service `json:"services"`
}

Schema defines the structure of a message flow schema containing services and their operations.

func MergeSchemas

func MergeSchemas(schemas ...Schema) Schema

MergeSchemas combines multiple Schema objects into a single Schema.

func (*Schema) Sort

func (s *Schema) Sort()

Sort sorts the services and their operations in a consistent order.

type SchemaExtractor

type SchemaExtractor interface {
	ExtractSchema(ctx context.Context) (Schema, error)
}

SchemaExtractor interface defines the contract for extracting schemas.

type SchemaFormatter

type SchemaFormatter interface {
	FormatSchema(ctx context.Context, s Schema, opts FormatOptions) (FormattedSchema, error)
}

SchemaFormatter interface defines the contract for formatting schemas.

type SchemaRenderer

type SchemaRenderer interface {
	RenderSchema(ctx context.Context, fs FormattedSchema) ([]byte, error)
}

SchemaRenderer interface defines the contract for rendering formatted schemas.

type Service

type Service struct {
	Name        string      `json:"name"`
	Description string      `json:"description,omitempty"`
	Operation   []Operation `json:"operations"`
}

Service represents a service in the message flow with its name and operations.

type Source

type Source interface {
	SchemaExtractor
}

Source interface defines the contract for schema extraction.

type Target

type Target interface {
	SchemaFormatter
	SchemaRenderer
	Capabilities() TargetCapabilities
}

Target interface defines the contract for schema formatting and rendering.

type TargetCapabilities

type TargetCapabilities struct {
	Format bool
	Render bool
}

TargetCapabilities represents the capabilities of a Target implementation.

type TargetType

type TargetType string

TargetType represents the type of target format for schema conversion.

type UnsupportedFormatError

type UnsupportedFormatError struct {
	// contains filtered or unexported fields
}

UnsupportedFormatError represents an error when an unsupported format is provided.

func (*UnsupportedFormatError) Error

func (err *UnsupportedFormatError) Error() string

Error implements the error interface for UnsupportedFormatError.

type UnsupportedFormatModeError

type UnsupportedFormatModeError struct {
	// contains filtered or unexported fields
}

UnsupportedFormatModeError represents an error when an unsupported format mode is provided.

func (*UnsupportedFormatModeError) Error

func (err *UnsupportedFormatModeError) Error() string

Error implements the error interface for UnsupportedFormatError.