Metadata-Version: 2.4
Name: trueconf-eraser
Version: 1.0.0
Summary: CLI tool to find and stop stale conferences on TrueConf Server
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: typer>=0.26.8
Requires-Dist: typing_extensions>=4.0
Requires-Dist: i18nice[YAML]>=0.16.0

<p align="center">
  <a href="https://trueconf.com" target="_blank" rel="noopener noreferrer">
    <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/TrueConf/.github/refs/heads/main/logos/logo-dark.svg">
      <img width="150" alt="trueconf" src="https://raw.githubusercontent.com/TrueConf/.github/refs/heads/main/logos/logo.svg">
    </picture>
  </a>
</p>

<h1 align="center">trueconf-eraser</h1>

<p align="center">A CLI utility that finds and stops stale conferences on TrueConf Server</p>

<p align="center">
    <a href="https://pypi.org/project/trueconf-eraser/">
        <img src="https://img.shields.io/pypi/v/trueconf-eraser">
    </a>
    <a href="https://pypi.org/project/trueconf-eraser/">
        <img src="https://img.shields.io/pypi/pyversions/trueconf-eraser">
    </a>
    <a href="https://pypi.org/project/trueconf-eraser/">
        <img src="https://static.pepy.tech/personalized-badge/trueconf-eraser?period=total&units=ABBREVIATION&left_color=GREY&right_color=BRIGHTGREEN&left_text=%D0%A1%D0%BA%D0%B0%D1%87%D0%B8%D0%B2%D0%B0%D0%BD%D0%B8%D0%B9" alt="PyPI Downloads">
    </a>
        <a href="https://t.me/trueconf_chat" target="_blank">
        <img src="https://img.shields.io/badge/Telegram-2CA5E0?logo=telegram&logoColor=white" />
    </a>
    <a href="https://discord.gg/2gJ4VUqATZ">
        <img src="https://img.shields.io/badge/Discord-%235865F2.svg?&logo=discord&logoColor=white" />
    </a>
    <a href="#">
        <img src="https://img.shields.io/github/stars/trueconf/trueconf-eraser?style=social" />
    </a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/TrueConf/trueconf-eraser/refs/heads/main/assets/banner.png" width="500" height="auto">
</p>

<p align="center">
  <a href="./README.md">English</a> /
  <a href="./README-ru.md">Русский</a>
</p>

> [!CAUTION]
> The tool is intended to be run by an experienced administrator from a trusted machine, do not run it on servers with other users or processes.

It scans all active conferences and terminates the ones that match the configured criteria:
- the conference has been running longer than allowed;
- the number of registered users and/or guests does not exceed the configured limits.

## 📋 How it works

1. Fetches all active conferences (`state=running`).
2. Determines the session start time from `/sessions`; if it is unavailable, falls back to the conference `created_at` (or `start_time`).
3. For every conference, checks the elapsed time and the participants.
4. Logs what is being stopped and why. With `--dry-run` nothing is actually stopped.

## 💻 Requirements

- Operating system: Linux, macOS or Windows.
- TrueConf Server with the API v4.
- An OAuth 2.0 application with the required permissions (see below).
- HTTPS access to the server's `/api/v4`.

## ⚙️ Setting up TrueConf Server

Before the first run, create an OAuth 2.0 application on the server and grant it the following permissions:

- `conferences:read`
- `conferences:write`
- `conferences.participants:read`
- `conferences.sessions:read`

See the [TrueConf Server API documentation](https://trueconf.ru/docs/server/ru/admin/api/) for details.

## 📦 Installation

With `pip`:

```bash
pip install trueconf-eraser
```

or with `uv`:

```bash
uv tool install trueconf-eraser
```

## 🛠 Usage

The tool ships two equivalent commands that do exactly the same thing:
- `tc-erase` — the primary command;
- `tc-clean` — a short alias.

### Parameters

| Parameter | Short | Description | Required |
|---|---|---|---|
| `--host` | `-h` | TrueConf Server host, e.g. `host.example.com` (`https://` is added automatically) or a full HTTPS URL | yes |
| `--client-id` | `-id` | OAuth 2.0 application ID | yes |
| `--client-secret` | `-s` | OAuth 2.0 application secret | yes |
| `--max-users` | `-u` | Max registered server users in a conference | yes |
| `--max-guests` | `-g` | Max guest participants in a conference | yes |
| `--max-session-duration` | `-d` | Max session duration in seconds | yes |
| `--dry-run` | | Simulate the run without stopping anything | no |
| `--verbose` | | Verbose output with debug information | no |
| `--no-verify-ssl` | | Disable TLS certificate verification | no |
| `--lang` | `-l` | Output language: `en` or `ru` (default: `en`) | no |

### Certificate verification

TLS certificate verification is enabled by default (the bundled CA store is used).

- **Public certificate (e.g. Let's Encrypt)** — works out of the box, no extra flags needed.
- **Self-signed certificate** — not present in the default trust store, so verification fails.
  To use one, pass `--no-verify-ssl`; note that this disables TLS certificate verification
  entirely and exposes the connection to MITM attacks, so use it only on trusted networks.

### Stop criteria

A conference is stopped when BOTH conditions are met:

1. Its duration exceeds `--max-session-duration`.
2. One of the participant conditions holds:
   - only registered server users and their count is ≤ `--max-users`;
   - only guests and their count is ≤ `--max-guests`;
   - both groups: registered users ≤ `--max-users` AND guests ≤ `--max-guests`.

### Examples

Dry run (recommended before the real run) — 1 or fewer registered users, 15 or fewer guests, sessions older than one hour:

```bash
# Dry run: shows what would be stopped, but does not stop anything
tc-erase --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15 --dry-run
```

Stop conferences with the same criteria:

```bash
# Real run: actually stops the conferences that match the criteria
tc-erase --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15
```

Short flags:

```bash
# The same command using short flags (-h, -id, -s, -d, -u, -g)
tc-erase -h host.example.com -id YOUR_CLIENT_ID -s YOUR_CLIENT_SECRET \
  -d 3600 -u 1 -g 15
```

Output in Russian:

```bash
# Force the Russian output with --lang ru
tc-erase --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15 --lang ru
```

An unsupported language falls back to English:

```bash
# Unsupported language code: the output automatically falls back to English
tc-erase --lang fr --host host.example.com --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET \
  --max-session-duration 3600 --max-users 1 --max-guests 15
```

## 🌍 Localization

Supported languages: `en` (default) and `ru`. If an unsupported language code is passed to `--lang`, the output falls back to English.

To add a new language:
1. Create `app/locales/<code>.yml` (see `en.yml` and `ru.yml` for the structure).
2. Add the code to `SUPPORTED_LANGS` in `app/localization.py`.

## 🩺 Troubleshooting

| Problem | Solution |
|---|---|
| Authentication error | Check `--client-id` and `--client-secret`; make sure the application has the required permissions |
| TLS/SSL certificate error | Only for self-signed certificates: add `--no-verify-ssl` |
| No session times available | The tool automatically falls back to the conference `created_at`/`start_time` |
| “No active conferences.” | Nothing to clean up right now — that is fine |
