Skip to content

Commit ea20a1c

Browse files
CopilotDanySK
Copilot
and
DanySK
committed
Changes before error encountered
Co-authored-by: DanySK <[email protected]>
1 parent 527000c commit ea20a1c

File tree

2 files changed

+212
-3
lines changed

2 files changed

+212
-3
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,4 +8,5 @@ data_summary_*
88
timeprocessed
99
.env
1010
.kotlin
11-
.DS_Store
11+
.DS_Store
12+
kotlin-js-store/

‎README.md‎

Lines changed: 210 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,211 @@
1-
# Collektive distributed example
1+
# Collektive Distributed Example
22

3-
Work in progress..
3+
[![CI/CD](https://github.com/Collektive/collektive-example-distributed/actions/workflows/dispatcher.yml/badge.svg)](https://github.com/Collektive/collektive-example-distributed/actions/workflows/dispatcher.yml)
4+
5+
A distributed example implementation of [Collektive](https://github.com/Collektive/collektive), demonstrating aggregate programming in a network of distributed devices using MQTT for communication.
6+
7+
## Overview
8+
9+
This project showcases how to build distributed aggregate computing applications using the Collektive framework. It implements a simple neighboring network where devices communicate via MQTT to exchange information about their neighbors, demonstrating the fundamental concepts of aggregate programming in a distributed environment.
10+
11+
## Features
12+
13+
- **Multiplatform Support**: Runs on both JVM and JavaScript (Node.js) platforms using Kotlin Multiplatform
14+
- **MQTT Communication**: Devices communicate using the MQTT protocol via a public broker
15+
- **Aggregate Programming**: Implements the `neighboring` operation to collect information from connected devices
16+
- **Configurable Network**: Customize the number of devices, round time, and execution duration
17+
- **Docker Support**: Includes Docker Compose configuration for containerized deployments
18+
19+
## Requirements
20+
21+
- **JDK**: Version 8 or higher
22+
- **Gradle**: Wrapper included (no installation required)
23+
- **Node.js**: Version 22.19 (for JavaScript target)
24+
- **Docker**: Optional, for containerized execution
25+
26+
## Installation
27+
28+
Clone the repository:
29+
30+
```bash
31+
git clone https://github.com/Collektive/collektive-example-distributed.git
32+
cd collektive-example-distributed
33+
```
34+
35+
## Usage
36+
37+
### Running on JVM
38+
39+
Run the distributed example on the JVM platform:
40+
41+
```bash
42+
./gradlew :distributed:jvmRun
43+
```
44+
45+
This will start 3 devices (IDs 0-2) that communicate via MQTT, each running aggregate cycles every second for 60 seconds.
46+
47+
### Running on JavaScript (Node.js)
48+
49+
Run the distributed example on Node.js:
50+
51+
```bash
52+
./gradlew :distributed:jsNodeDevelopmentRun
53+
```
54+
55+
This will start 2 devices (IDs 2-3) using the JavaScript implementation.
56+
57+
### Customizing Parameters
58+
59+
The main entrypoint accepts several parameters:
60+
61+
- `deviceCount`: Number of devices in the network (default: 50)
62+
- `startDeviceId`: Starting device ID (default: 0)
63+
- `roundTime`: Time between aggregate cycles (default: 1 second)
64+
- `executeFor`: Total execution duration (default: 60 seconds)
65+
- `asyncNetwork`: Whether to use asynchronous network mode (default: false)
66+
67+
Modify the parameters in `distributed/src/jvmMain/kotlin/it/unibo/collektive/Main.kt` or `distributed/src/jsMain/kotlin/it/unibo/collektive/Main.kt` to customize behavior.
68+
69+
### Building
70+
71+
Build the entire project:
72+
73+
```bash
74+
./gradlew build
75+
```
76+
77+
This will compile both JVM and JavaScript targets and run code quality checks (ktlint, detekt).
78+
79+
### Running Tests
80+
81+
Execute all tests:
82+
83+
```bash
84+
./gradlew test
85+
```
86+
87+
### Code Quality
88+
89+
Run linting and static analysis:
90+
91+
```bash
92+
./gradlew ktlintCheck detektAll
93+
```
94+
95+
Auto-fix linting issues:
96+
97+
```bash
98+
./gradlew ktlintFormat
99+
```
100+
101+
## Docker Compose
102+
103+
The project includes a Docker Compose configuration for running simulations and generating charts. The workflow consists of:
104+
105+
1. **prepare**: Sets up directories with proper permissions
106+
2. **simulation**: Runs the distributed simulation
107+
3. **charts**: Generates visualization charts from simulation data
108+
4. **finish**: Adjusts file permissions for output
109+
110+
Build and run with Docker Compose:
111+
112+
```bash
113+
docker compose build
114+
docker compose up
115+
```
116+
117+
Results will be available in:
118+
- `./data`: Simulation output data
119+
- `./charts`: Generated visualizations
120+
121+
## Project Structure
122+
123+
```
124+
collektive-example-distributed/
125+
├── distributed/ # Main module
126+
│ └── src/
127+
│ ├── commonMain/ # Shared Kotlin code
128+
│ │ └── kotlin/
129+
│ │ └── it/unibo/collektive/
130+
│ │ ├── CommonEntrypoint.kt # Main aggregate program logic
131+
│ │ └── network/ # MQTT mailbox implementation
132+
│ ├── jvmMain/ # JVM-specific code
133+
│ │ └── kotlin/
134+
│ │ └── it/unibo/collektive/
135+
│ │ └── Main.kt # JVM entry point
136+
│ └── jsMain/ # JavaScript-specific code
137+
│ └── kotlin/
138+
│ └── it/unibo/collektive/
139+
│ └── Main.kt # JavaScript entry point
140+
├── buildSrc/ # Build configuration
141+
├── gradle/ # Gradle wrapper and version catalog
142+
├── docker-compose.yml # Docker Compose configuration
143+
├── release.config.js # Semantic release configuration
144+
└── README.md # This file
145+
```
146+
147+
## Technologies
148+
149+
- **[Collektive](https://github.com/Collektive/collektive)**: Aggregate programming DSL (v26.1.2)
150+
- **Kotlin**: Multiplatform programming language (v2.2.20)
151+
- **MQTT**: Message protocol for distributed communication
152+
- **[MKTT](https://github.com/nfacha/MKTT)**: Kotlin Multiplatform MQTT client
153+
- **[HiveMQ](https://www.hivemq.com/)**: MQTT client library (JVM)
154+
- **Kotlinx Serialization**: Data serialization (JSON and Protobuf)
155+
- **Kotlinx Coroutines**: Asynchronous programming
156+
- **Kotlin Logging**: Structured logging
157+
- **Docker**: Containerization platform
158+
159+
## How It Works
160+
161+
1. **Device Initialization**: Each device creates an MQTT mailbox connected to a public broker (`test.mosquitto.org`)
162+
2. **Aggregate Program**: Devices run an aggregate program that collects neighbor information using the `neighboring` operation
163+
3. **Communication**: Devices exchange messages via MQTT, broadcasting their state and receiving updates from neighbors
164+
4. **Cycles**: Each device periodically executes aggregate cycles, processing received messages and updating its local state
165+
5. **Output**: Devices log their current neighbor list after each cycle
166+
167+
## Development
168+
169+
### Git Hooks
170+
171+
The project uses pre-commit hooks to ensure code quality:
172+
173+
- **Commit message validation**: Enforces conventional commits
174+
- **Code checks**: Runs `detektAll` and `ktlintCheck` before commits
175+
176+
Hooks are automatically installed when building the project.
177+
178+
### Continuous Integration
179+
180+
The project uses GitHub Actions for CI/CD:
181+
182+
- Builds and tests on multiple platforms (Ubuntu, macOS, Windows)
183+
- Runs code quality checks
184+
- Automated dependency updates via Renovate
185+
- Automated releases using semantic-release
186+
187+
## Contributing
188+
189+
Contributions are welcome! Please follow these guidelines:
190+
191+
1. Fork the repository
192+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
193+
3. Commit your changes using conventional commits
194+
4. Ensure all tests pass and code quality checks succeed
195+
5. Push to the branch (`git push origin feature/amazing-feature`)
196+
6. Open a Pull Request
197+
198+
## License
199+
200+
This project is part of the [Collektive](https://github.com/Collektive) ecosystem. Please refer to the main Collektive repository for license information.
201+
202+
## Related Projects
203+
204+
- [Collektive](https://github.com/Collektive/collektive): The main Collektive DSL and runtime
205+
- [Collektive Stdlib](https://github.com/Collektive/collektive): Standard library for aggregate programming
206+
207+
## Support
208+
209+
For questions, issues, or contributions, please visit:
210+
- [Issue Tracker](https://github.com/Collektive/collektive-example-distributed/issues)
211+
- [Discussions](https://github.com/Collektive/collektive-example-distributed/discussions)

0 commit comments

Comments
 (0)