🚀 Dispatcher Service

A service that reconstructs a valid flight itinerary from a list of airline tickets.

📋 Service Description

The Dispatcher service is a RESTful API that takes a list of flight tickets as input and reconstructs a valid itinerary that visits all destinations exactly once. It uses a modified version of Hierholzer's algorithm to find a valid path.

The service handles various edge cases and validates the input to ensure that the itinerary is valid:

• No duplicate tickets (same source and destination)
• No cycles in the itinerary
• Valid starting and ending points

📦 Prerequisites

To run this service locally, you need:

• Docker
• Docker Compose

No Go installation is required as the service runs in a Docker container.

🏃 Running the Service Locally

Using Docker Compose

1. Clone the repository:

git clone https://github.com/dsha256/dispatcher.git
cd dispatcher

2. Start the service using Docker Compose:

docker compose up --build

Alternatively, if you have Task installed:

task compose-up

The service will be available at http://localhost:3000.

3. To stop the service:

docker compose down --remove-orphans --volumes

Or with Task:

task compose-down

🔌 API Endpoints

Reconstruct Itinerary

Reconstructs a valid flight itinerary from a list of airline tickets.

• URL: /api/v1/dispatcher/itinerary
• Method: POST
• Content-Type: application/json

Request Body

{
  "tickets": [
    ["LAX", "DXB"],
    ["JFK", "LAX"],
    ["SFO", "SJC"],
    ["DXB", "SFO"]
  ]
}

Success Response

• Code: 200 OK
• Content:

{
  "status": "success",
  "message": "",
  "data": {
    "linear_path": ["JFK", "LAX", "DXB", "SFO", "SJC"]
  }
}

Error Response

• Code: 400 Bad Request
• Content:

{
  "status": "error",
  "message": "multiple same destination",
  "err": "multiple same destination"
}

Health Checks

The service provides two health check endpoints:

• Liveness: /api/v1/liveness - Checks if the service is running
• Readiness: /api/v1/readiness - Checks if the service is ready to process requests

🔍 Example Requests Using curl

Reconstruct Itinerary

curl -X POST http://localhost:3000/api/v1/dispatcher/itinerary \
  -H "Content-Type: application/json" \
  -d '{
    "tickets": [
      ["LAX", "DXB"],
      ["JFK", "LAX"],
      ["SFO", "SJC"],
      ["DXB", "SFO"]
    ]
  }'

Health Checks

# Liveness check
curl http://localhost:3000/api/v1/liveness

# Readiness check
curl http://localhost:3000/api/v1/readiness

🧪 Running Tests

Using Docker

You can run tests inside a Docker container:

docker run --rm -v $(pwd):/app -w /app golang:1.24-alpine go test -v -race ./...

Using Task

If you have Task installed:

task test

This will run all tests in verbose mode with race detection enabled.

Running Specific Tests

To run specific tests:

# Run unit tests for the dispatcher package
go test -v -race ./internal/dispatcher

# Run integration tests for the handler package
go test -v -race ./internal/handler

👨‍💻 Development

The service is built with Go 1.24 and uses the following components:

• Standard library HTTP server
• Custom middleware for logging and error recovery
• JSON for request/response serialization