# Tokens

Plik opisuje aktualny model pracy z tokenami w launcherze.

## Zrodlo prawdy

Sa dwa miejsca, w ktorych moga byc zapisane tokeny:

- remote URL-e w repo, na przyklad `http://LOGIN:TOKEN@host/org/repo.git`
- lokalny plik `~/dev/workspace/rv/tokens/tokens.json`

Jesli remote URL zawiera `LOGIN:TOKEN@...`, to remote jest zrodlem prawdy.
Launcher moze wtedy zeskanowac repo i zapisac ten token do `tokens.json`.

Jesli remote nie ma tokena, `tokens.json` moze byc uzyty jako lokalny store
przy operacjach `tokens write` i `tokens update --from store`.

## Format `tokens.json`

Tokeny sa trzymane per endpoint serwera, a dopiero pod nim per user i token:

```json
{
  "version": 2,
  "servers": {
    "http://77.90.8.171:3001": {
      "type": "gitea",
      "scheme": "http",
      "host": "77.90.8.171",
      "port": 3001,
      "users": {
        "u1": {
          "tokens": {
            "t1": "SECRET"
          }
        }
      }
    }
  }
}
```

To pozwala odroznic:

- typ serwera, na przyklad `gitea`, `github`, `gitlab`, `unknown`
- endpoint, czyli `scheme + host + port`
- uzytkownikow na danym serwerze
- wiele tokenow dla jednego usera

## Skanowanie remota

Przy `tokens scan` launcher:

- czyta wszystkie remote URL-e w repo
- czyta `tokens.json`
- laczy remote i store w pary po endpoincie serwera
- wybiera tylko `http` i `https`
- jesli URL ma `LOGIN:TOKEN@...`, wyciaga login i token
- zapisuje je pod odpowiednim endpointem w `tokens.json`

Endpoint jest liczony z:

- scheme
- host
- port

Przy skanowaniu launcher zapisuje tez metadane serwera:

- `type`
- `scheme`
- `host`
- `port`

## Komendy

### `tokens scan`

Zrodla:

```text
repo + tokens.json
```

Dzialanie:

- skanuje remote URL-e w repo
- czyta wpisy z `tokens.json`
- laczy oba zrodla po endpoincie serwera
- zapisuje znalezione tokeny do `tokens.json`
- zapisuje je per endpoint serwera
- wypisuje domyslnie tylko waska tabele `items`
- z `--verbose` dopisuje diagnostyczne sekcje `context` oraz `scan`

Tabela `items` porownuje dwa zrodla dla tego samego endpointu. Ten sam `item`
moze miec dwa wiersze:

- `source=repo` - stan remote URL-i w repo
- `source=tokens.json` - stan lokalnego store tokenow

Dzieki temu widac, dla ktorego endpointu token jest w remote, a dla ktorego
jest tylko w `tokens.json`.

Kolumny w tabeli `items`:

- `item` - numer porownywanego endpointu
- `source` - `repo` albo `tokens.json`
- `id` - identyfikator miejsca tokena: remote `r1` dla repo albo token `t1` dla `tokens.json`
- `server` - typ serwera, na przyklad `gitea`
- `scheme` - schemat URL, na przyklad `http`
- `host` - host endpointu, na przyklad `77.90.8.171`
- `port` - port endpointu, na przyklad `3001`
- `credential` - typ wpisu: `auth`, `plain`, `store` albo `missing`
- `repo_user` - login odczytany z remote URL-i repo
- `store_user` - login odczytany z `tokens.json`
- `token` - `yes` albo `no`, czyli czy dane zrodlo ma token dla endpointu
- `sync` - `yes` albo `no`, czyli czy para repo/store jest zgodna

Tabela nie wypisuje sekretu tokena. Jezeli token jest w remote, `id` pokazuje
nazwe remota, na przyklad `r1`. Jezeli token jest w `tokens.json`, `id`
pokazuje nazwe tokenu, na przyklad `t1`.

Przyklad:

```bash
./rvctl tokens scan
./rvctl tokens scan --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens scan --verbose
```

### `tokens read`

Pokazuje szczegolowa zawartosc `tokens.json`.

Wynik zawiera:

- endpoint
- type
- scheme
- host
- port
- users
- tokens

Oraz liste userow i nazw tokenow dla kazdego endpointu.

Przyklad:

```bash
./rvctl tokens read
./rvctl tokens read --server http://77.90.8.171:3001
./rvctl tokens read --show-secrets
```

### `tokens stats`

Pokazuje statystyki per endpoint serwera i porownuje dwa zrodla:

- endpointy znalezione w remote URL-ach repo
- endpointy zapisane w `tokens.json`

Wynik ma ten sam model porownania co `tokens scan`, ale nie zapisuje zmian:

- liczbe endpointow w repo
- liczbe endpointow w store
- laczna unie endpointow
- statusy zgodnosci, na przyklad `in_sync`, `store_ahead`, `repo_ahead`
- tabele `items`, w ktorej repo i `tokens.json` sa osobnymi wierszami tego samego itemu

Przyklad:

```bash
./rvctl tokens stats --repo ~/dev/workspace/rv/series/inf/03
```

### `tokens write`

Kierunek:

```text
tokens.json -> repo
```

Dzialanie:

- bierze token z `tokens.json`
- wybiera endpoint, usera i token
- wpisuje dane auth do wybranego remota repo

Przyklad:

```bash
./rvctl tokens write \
  --repo ~/dev/workspace/rv/series/inf/03 \
  --remote r1 \
  --server http://77.90.8.171:3001 \
  --user u1 \
  --token-name t1
```

### `tokens update`

Uruchamia synchronizacje w zadanym kierunku.

Dozwolone kierunki:

- `tokens update --from remotes`
- `tokens update --from store`

Przyklad:

```bash
./rvctl tokens update --from remotes --repo ~/dev/workspace/rv/series/inf/03
./rvctl tokens update --from store --repo ~/dev/workspace/rv/series/inf/03 --remote r1 --server http://77.90.8.171:3001 --user u1 --token-name t1
```

## Konflikty

Domyslnie launcher nie zgaduje przy konflikcie.

Jesli:

- token jest w repo, ale nie ma go w `tokens.json`
  uzyj `tokens scan`
- token jest w `tokens.json`, ale nie ma go w repo
  uzyj `tokens write`
- token jest i tu, i tu, ale wartosci sa rozne
  wybierz kierunek jawnie przez `tokens update --from ...`

Przy `tokens write` i `tokens update --from store` mozna uzyc:

- `--replace`
- `--dry-run`

## Rekomendacja

Najbezpieczniejszy model pracy:

- `tokens scan` do zczytywania danych z remote'ow
- `tokens read` do podgladu store
- `tokens stats` do zbiorczego przegladu per endpoint
- `tokens write` do jawnego wpisania auth do remota
- `tokens update --from ...` tylko z jawnym kierunkiem