GoTomato/README.md

# 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": ""}`                                                                                        |
| `updateSettings` | Update Pomodoro settings              | `{"command": "updateSettings", "password": "", "settings": {"work": 600, "shortBreak": 60, "longBreak": 300, "sessions": 2}}` |

#### Update Settings Command (`updateSettings`)

The `updateSettings` command allows clients to modify the Pomodoro timer configuration, including the length of work sessions, short breaks, long breaks, and the total number of sessions in a cycle. This command must include a valid password to be accepted by the server. The updateSettings command can be used when the timer is stopped.

- Fields in the `settings` Object:
  - `work`: Length of the work session (in seconds).
  - `shortBreak`: Length of the short break (in seconds).
  - `longBreak`: Length of the long break (in seconds).
  - `sessions`: Total number of work/break sessions in the Pomodoro cycle.

All fields are mandatory and may not be ommitted.

### 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 ("Focus", "ShortBreak", "LongBreak", "End" or "Idle").
  - "End" is send only once, after all sessions are finished
- settings: Contains the current Pomodoro settings:
    -  work: Length of the work session in seconds (e.g., 1500 for 25 minutes).
    -  shortBreak: Length of the short break in seconds (e.g., 300 for 5 minutes).
    -  longBreak: Length of the long break in seconds (e.g., 900 for 15 minutes).
    -  sessions: The total number of work/break sessions (e.g., 4).
- session: The current session number (e.g., 1 for the first work session).
- time_left: The remaining time for the current mode, in seconds (e.g., 900 for 15 minutes).
- ongoing: Whether a Pomodoro session is currently ongoing.
- paused: Whether the timer is paused.
- version: The protocol version of the send message (this is always the same as the major app version)

| Message Type      | Example                                                                                                                                                                       |
| ---               | ---                                                                                                                                                                           |
| Welcome Message   | {"mode":"Idle", "settings":{"work":1500, "shortBreak":300, "longBreak":900, "sessions":4}, "session":0, "time_left":1500, "ongoing":false, "paused":false, "version":"0"}    |
| Session Running   | {"mode":"Focus", "settings":{"work":1500, "shortBreak":300, "longBreak":900, "sessions":4}, "session":1, "time_left":900, "ongoing":true, "paused":false, "version":"0"}      |
| Session Running   | {"mode":"ShortBreak", "settings":{"work":1500, "shortBreak":300, "longBreak":900, "sessions":4}, "session":2, "time_left":50, "ongoing":true, "paused":false, "version":"0"} |
| Session Paused    | {"mode":"Focus", "settings":{"work":1500, "shortBreak":300, "longBreak":900, "sessions":4}, "session":2, "time_left":456, "ongoing":true, "paused":true, "version":"0"}       |
| Session End/Reset | {"mode":"End", "settings":{"work":1500, "shortBreak":300, "longBreak":900, "sessions":4}, "session":0, "time_left":0, "ongoing":false, "paused":false, "version":"0"}        |

## Testing

```
docker run --rm -d --name pomodoro-client -v $PWD:/usr/share/nginx/html/ -p 8081:80 nginx
go run .
```

open http://localhost:8081

## Building

```
go build -ldflags "-w"
upx --best --lzma GoTomato
```