Add real-time streaming endpoint and improve error handling

- Added new /run_simulation_stream endpoint for SSE streaming
- Improved parameter validation with better error messages
- Changed error response code from 500 to 400 for invalid parameters
- Reorganized test suite into separate files
- Updated documentation with streaming endpoint examples
- Refactored code to reduce duplication and improve maintainability

Author: MirkoZETA

.github/workflows/README_DEV.md .github/workflows/README.md.github/workflows/README_DEV.md renamed to .github/workflows/README.md

@@ -43,8 +43,11 @@ This guide helps developers set up, test, and deploy the Flex Net Sim Backend AP
    # Test help endpoint
    curl http://127.0.0.1:5000/help
 
-   # Test simulation endpoint
+   # Test standard simulation endpoint
    curl -X POST -H "Content-Type: application/json" -d '{}' http://127.0.0.1:5000/run_simulation
+   
+   # Test streaming simulation endpoint
+   curl -N -X POST -H "Content-Type: application/json" -d '{"goalConnections": 50000}' http://127.0.0.1:5000/run_simulation_stream
    ```
 
 ## Testing
@@ -119,7 +122,11 @@ Follow the Google Cloud setup steps from the video, focusing on:
     Use the `curl` command with the `ENDPOINT-URL` you obtained from the previous steps to test your deployed API. Replace `YOUR-ENDPOINT-URL` with the actual `ENDPOINT-URL`.
 
     ```bash
+    # Test standard endpoint
     curl -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "networkType": 1, "bitrate": "fixed-rate"}' <YOUR-ENDPOINT-URL>/run_simulation
+    
+    # Test streaming endpoint
+    curl -N -X POST -H "Content-Type: application/json" -d '{"algorithm": "FirstFit", "goalConnections": 5000000}' <YOUR-ENDPOINT-URL>/run_simulation_stream
     ``` 
 
     Remember that depending on the authetification preferences you might need to authetificate to send request to the Endpoint just created.

.gitignore

@@ -10,4 +10,7 @@ simulation.out
 # Test files
 .coverage
 htmlcov
-.pytest_cache
+.pytest_cache
+
+# Claude Code
+CLAUDE.md

CHANGELOG.md

@@ -5,15 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
-
 ### ROADMAP
 - Switch to Flex Net Sim v0.8.2.
 - Enhance previous algorithms.
 - Add algorithm BestFit.
 - Switch to new domain.
 
-## [1.1.1] - 2023-03-01
+## [2.0.0] - 2025-03-xx
+
+### Added
+- New `/run_simulation_stream` endpoint for streaming simulation results in real-time
+- Refactored backend code to reduce duplication and improve maintainability
+- Added unit tests for the streaming endpoint
+- Modified `simulator.hpp` to flush stdout after each line for better streaming support (see `src/README.md`)
+- Improved help endpoint with more concise documentation
+
+### Changed
+- Standardized API response format for better consistency:
+  - Success responses now use `status: "success"` with data in a `data` field
+  - Error responses now use `status: "error"` with a `message` and detailed `error` fields
+  - Streaming responses include event types and structured JSON data
+- Reorganized test suite into separate files for better maintainability
+- Improved parameter validation with descriptive error messages
+- Changed error response code from 500 to 400 for invalid parameters
+- Moved parameter validation from C++ to the API layer for better user experience
+
+## [1.1.1] - 2025-03-01
 
 ### Added
 - Deployed coverage to pages
@@ -60,5 +77,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - API allocated in cloud run.
 - Documentation README for the process of develop/deployment located in [workflows](https://github.com/MirkoZETA/FlexNetSim-API/tree/master/.github/workflows/README_DEV.md).
 
-[1.1.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v1.1.0
 [1.0.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v1.0.0
+[1.1.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v1.1.0
+[2.0.0]: https://github.com/MirkoZETA/FlexNetSim-API/releases/tag/v2.0.0

README.md

@@ -34,7 +34,7 @@ For development and deployment instructions for this API, refer to [README_DEV.m
 
 ### `/run_simulation` (POST)
 
-Runs a network simulation with the provided parameters.
+Runs a network simulation with the provided parameters and returns complete results.
 
 #### Request Parameters
 
@@ -74,9 +74,84 @@ curl -X POST -H "Content-Type: application/json" \
 https://fns-api-cloud-run-787143541358.us-central1.run.app/run_simulation
 ```
 
+#### Response Format
+
+```json
+{
+  "status": "success",
+  "data": "simulation results as text..."
+}
+```
+
+#### Response Codes
+
+- `200 OK`: Success
+- `400 Bad Request`: Invalid parameters
+- `500 Internal Server Error`: Server-side error
+
+### `/run_simulation_stream` (POST)
+
+Runs a network simulation with the provided parameters and streams results in real-time using Server-Sent Events (SSE).
+
+#### Request Parameters
+
+Same parameters as `/run_simulation` endpoint.
+
+#### Example: Streaming with Default Parameters
+
+```bash
+curl -N -X POST -H "Content-Type: application/json" -d '{}' \
+  http://localhost:5000/run_simulation_stream
+```
+
+#### Example: Streaming with Custom Parameters
+
+```bash
+curl -N -X POST -H "Content-Type: application/json" \
+-d '{ 
+  "algorithm": "FirstFit",
+  "networkType": 1,
+  "goalConnections": 5000000,
+  "confidence": 0.05,
+  "lambdaParam": 120,
+  "mu": 1,
+  "network": "NSFNet",
+  "bitrate": "fixed-rate"
+}' \
+http://localhost:5000/run_simulation_stream
+```
+
+#### Response Format
+
+The endpoint returns a stream of Server-Sent Events with the following event types:
+
+1. **Start Event**:
+   ```
+   event: start
+   data: {"status": "started", "message": "Simulation started"}
+   ```
+
+2. **Data Events** (multiple events, one per line of output):
+   ```
+   event: data
+   data: {"status": "running", "data": "Line of simulation output"}
+   ```
+
+3. **End Event**:
+   ```
+   event: end
+   data: {"status": "completed", "message": "Simulation completed"}
+   ```
+
+4. **Error Event** (only if an error occurs):
+   ```
+   event: error
+   data: {"status": "error", "message": "Error description", "error": "Detailed error"}
+   ```
+
 #### Response Codes
 
-- `200 OK`: Success. Returns `{"output": "...", "error": ""}`
+- `200 OK`: Success (stream starts)
 - `400 Bad Request`: Invalid parameters
 - `500 Internal Server Error`: Server-side error