WizardMerge/DROGON_CONVERSION.md

Backend Conversion to Drogon - Implementation Summary

Overview

The WizardMerge C++ backend has been successfully converted from a command-line interface (CLI) application to a modern HTTP API server using the Drogon web framework.

Changes Made

1. Core Architecture Changes

HTTP Server Implementation

• New: src/main.cpp - Now runs as an HTTP server using Drogon
• Previous: CLI tool that processed files directly
• Current: HTTP API server that accepts JSON requests

API Controller

• Added: src/controllers/MergeController.h - HTTP controller interface
• Added: src/controllers/MergeController.cc - Controller implementation
• Endpoint: POST /api/merge - Performs three-way merge operations

2. Build System Updates

Dependencies

• Added: Drogon framework (via Conan)
• Updated: conanfile.py - Added Drogon 1.9.3 dependency
• Updated: CMakeLists.txt - Integrated Drogon, made it optional

Build Flexibility

The build system now supports multiple installation methods:

1. Conan - Automatic dependency management
2. Docker - Containerized deployment
3. Manual - Direct system installation of Drogon
4. Library-only - Build without Drogon (library remains functional)

3. Configuration

Server Configuration

• Added: config.json - Drogon server configuration
  • Port: 8080 (default)
  • Threads: 4
  • Logging: INFO level to ./logs
  • Max body size: 10MB

4. Deployment Support

Docker

• Added: Dockerfile - Multi-stage build for production deployment
• Added: docker-compose.yml - Easy orchestration

Installation Script

• Added: install_drogon.sh - Automated Drogon installation from source

Build Script Enhancement

• Updated: build.sh - Now supports multiple build paths with fallbacks

5. Documentation

API Documentation

• Updated: backend/README.md - Comprehensive API documentation
• Added: examples/README.md - API usage examples
• Updated: BUILD.md - Updated build instructions
• Updated: Main README.md - Architecture overview

Examples

• Added: examples/api_client.py - Python client example
• Added: examples/test_api.sh - curl-based test scripts

API Specification

Endpoint: POST /api/merge

Request Format:

{
  "base": ["line1", "line2", "..."],
  "ours": ["line1", "line2", "..."],
  "theirs": ["line1", "line2", "..."]
}

Response Format:

{
  "merged": ["merged_line1", "merged_line2", "..."],
  "conflicts": [
    {
      "start_line": 0,
      "end_line": 5,
      "base_lines": ["..."],
      "our_lines": ["..."],
      "their_lines": ["..."]
    }
  ],
  "has_conflicts": false
}

Error Responses:

• 400 Bad Request - Invalid JSON or missing fields
• 500 Internal Server Error - Processing error

Deployment Options

1. Docker (Recommended for Production)

docker-compose up -d

2. Direct Installation

./install_drogon.sh
./build.sh
cd build && ./wizardmerge-cli

3. Development

./build.sh
cd build && ./wizardmerge-cli config.json

Backward Compatibility

Library Compatibility

• The core merge library (libwizardmerge.a) remains unchanged
• All existing merge algorithms work identically
• Unit tests continue to pass without modification

Breaking Changes

• CLI interface removed (replaced with HTTP API)
• Direct file I/O removed (now uses JSON over HTTP)

Migration Path

For users needing CLI functionality:

1. Use the HTTP API with curl/scripts
2. Write a thin CLI wrapper around the HTTP API
3. Link against libwizardmerge.a directly in custom applications

Testing

Unit Tests

• All existing unit tests pass
• Tests use the library directly, unaffected by HTTP layer

Integration Testing

• Python client example demonstrates API usage
• Shell script examples for curl-based testing
• Docker-based deployment testing

Security

Security Analysis

• CodeQL scan: No vulnerabilities found
• Code review: All issues addressed

Security Features

• JSON validation on all inputs
• Request body size limits (10MB default)
• Type-safe JSON conversions
• Exception handling for all endpoints

Performance Considerations

Drogon Benefits

• High-concurrency, non-blocking I/O
• 150k+ requests/sec capability
• Multi-threaded request processing (4 threads default)
• HTTP/1.1 support with keep-alive

Resource Usage

• Minimal memory footprint
• Efficient JSON parsing with JsonCpp
• Static library linking for core algorithms

Future Enhancements

Potential Improvements

1. WebSocket support for real-time conflict resolution
2. Additional endpoints for batch processing
3. File upload support for direct file merging
4. Authentication/authorization layer
5. Rate limiting for production use
6. Metrics and monitoring endpoints

Scalability

• Horizontal scaling via load balancer
• Stateless design allows multiple instances
• Docker Swarm or Kubernetes ready

Files Changed/Added

Modified Files

• backend/CMakeLists.txt - Build configuration
• backend/conanfile.py - Dependencies
• backend/src/main.cpp - Server implementation
• backend/build.sh - Build script
• backend/README.md - Documentation
• BUILD.md - Build guide
• README.md - Main documentation

Added Files

• backend/config.json - Server configuration
• backend/Dockerfile - Container definition
• backend/docker-compose.yml - Orchestration
• backend/install_drogon.sh - Installation script
• backend/src/controllers/MergeController.h - Controller header
• backend/src/controllers/MergeController.cc - Controller implementation
• backend/examples/README.md - Examples documentation
• backend/examples/api_client.py - Python client
• backend/examples/test_api.sh - Shell test scripts

Conclusion

The conversion to Drogon provides a modern, scalable HTTP API while maintaining the core merge algorithm functionality. The implementation includes comprehensive documentation, multiple deployment options, and maintains backward compatibility at the library level. The flexible build system ensures developers can work in various environments, from containerized deployments to manual installations.