Sebastian Mark
f991ba885d
- introduce password flag in server command line options - update clientCommand model - add password requirement for controlling the Pomodoro timer - document password in README
83 lines
4.2 KiB
Markdown
83 lines
4.2 KiB
Markdown
# GoTomato
|
|
|
|
A pomodoro server written in Go
|
|
|
|
[[_TOC_]]
|
|
|
|
## Installation
|
|
|
|
`go install git.smsvc.net/pomodoro/GoTomato@latest`
|
|
|
|
## Usage
|
|
|
|
See `GoTomato --help` for Parameters
|
|
|
|
## Client Commands and Server Messages
|
|
|
|
This section describes the WebSocket commands that clients can send to the Pomodoro server and the messages that the server sends to clients during a Pomodoro session.
|
|
|
|
### Message Format
|
|
|
|
Both client commands (sent to the server) and server messages (sent to the client) use the JSON format. The structure of these messages are described in the sections below.
|
|
|
|
### Client Commands
|
|
|
|
Clients communicate with the server by sending JSON-encoded commands. Each command must include a `command` field specifying the action to perform and the control `password` required to manage the Pomodoro timer. The password is set by the server (see [Usage](#usage)).
|
|
|
|
If the client sends a command with an incorrect password it will not be allowed to control the Pomodoro, but will still receive server messages (see below). By default the password is an empty string which allows everyone to control the Pomodoro. In this case, the `password` field may be omitted in the client's command.
|
|
|
|
Here are the available commands:
|
|
|
|
| Command | Action | Example Sent by Client |
|
|
|----------|-------------------------------------|-----------------------------------|
|
|
| `start` | Starts a new Pomodoro session | `{"command": "start", "password": ""}` |
|
|
| `pause` | Pauses the current session | `{"command": "pause", "password": ""}` |
|
|
| `resume` | Resumes a paused session | `{"command": "resume", "password": ""}` |
|
|
| `reset` | Stops and resets the current session| `{"command": "reset", "password": ""}` |
|
|
|
|
#### Optional Start Parameters
|
|
|
|
The Start-Command may contain an optional Pomodoro-Config, which allows you to customize the length of the work session, short break, long break, and the number of sessions. If no configuration is provided, the server will use default values.
|
|
|
|
Example:
|
|
```json
|
|
{
|
|
command: "start",
|
|
password: "foobar",
|
|
config: {
|
|
"work": 10, // Length of the work session in seconds
|
|
"shortBreak": 5, // Length of the short break in seconds
|
|
"longBreak": 10, // Length of the long break in seconds
|
|
"sessions": 2 // Number of total sessions
|
|
}
|
|
}
|
|
```
|
|
|
|
### Server Messages
|
|
|
|
The server periodically (every second) sends JSON-encoded messages to all connected clients to update them on the current state of the Pomodoro session.
|
|
These messages contain the following fields:
|
|
|
|
- mode: Indicates the current phase of the Pomodoro session ("Work", "ShortBreak", "LongBreak", or empty if no session is running).
|
|
- session: The current session number (e.g., 1 for the first work session).
|
|
- total_sessions: The total number of sessions for the current Pomodoro cycle (e.g., 4 if the cycle consists of 4 work/break sessions).
|
|
- time_left: The remaining time for the current mode, in seconds (e.g., 900 for 15 minutes).
|
|
- ongoing: Wether a pomodoro is currently ongoing
|
|
- paused: Wether the timer is paused
|
|
|
|
| Message Type | Example |
|
|
| --------------------- | --------------------------------------------------- |
|
|
| Welcome Message | `{"mode": "", "session":0, "total_sessions":0, "time_left":0, "ongoing": false, "paused": false}` |
|
|
| Session Running | `{"mode": "Work", "session": 1, "total_sessions": 4, "time_left": 900, "ongoing": true, "paused": false}` |
|
|
| Session Running | `{"mode": "ShortBreak", "session": 2, "total_sessions": 4, "time_left": 50, "ongoing": true, "paused": false}` |
|
|
| Session Paused | `{"mode": "Work", "session": 2, "total_sessions": 4, "time_left": 456, "ongoing": true, "paused": true}` |
|
|
| Session End/Reset | `{"mode": "", "session": 0, "total_sessions": 0, "time_left": 0, "ongoing": false, "paused": false}` |
|
|
|
|
## Testing
|
|
|
|
```
|
|
docker run --rm -d --name pomodoro-client -v $PWD:/usr/share/nginx/html/ -p 8081:80 nginx
|
|
go run .
|
|
```
|
|
|
|
open http://localhost:8081
|