Projekt weight-gateway¶
Zadanie: A-19606 Aplikacja weight-gateway dla wagi Drogbruk Piła
Cel¶
Serwis, który nasłuchuje na połączenia TCP (port 14002) i serwuje ostatnio odczytany rekord dla Apollo jako odpowiedź na żądanie HTTP. Dodatkowy panel administracyjny jako narzędzie dla testerów i supportu, razem z mockiem wagi.


Główne założenia odbioru rekordu:
- Rozdziela rekordy (odczyt wagi) na podstawie CRLF.
- Tylko liczba całkowita od 1 do 6 znaków (0–999999), bez znaku.
- Ostatni rekord jest przechowywany w pamięci także po rozłączeniu wagi. Jest serwowany tylko dopóki jest świeży (domyślnie 5 s), potem serwis zwraca błąd
STALE.
A. Aplikacja dla wagi¶
1. Repozytorium z multi-projektem Gradle (S)¶
Repozytorium weight-gateway to multi-projekt Gradle (dokumentacja).
Moduły (settings.gradle):
| Moduł | Rodzaj | Rola |
|---|---|---|
weight-protocol |
biblioteka Java | model rekordu, parser pakietów, klasyfikator |
tcp-service |
aplikacja Grails | nasłuch TCP od MOXA + endpoint HTTP dla Apollo |
admin |
aplikacja Grails | panel administracyjny, w tym strona symulatora wagi |
mock |
biblioteka Java + CLI | symulator wagi (klient TCP) |
2. Czas uruchomienia aplikacji¶
TODO. Nie mamy jeszcze pomiaru.
Do zmierzenia: czas od startu procesu do otwarcia portu TCP i do pierwszej poprawnej odpowiedzi GET /weight.
B. Protokół wagi (weight-protocol)¶
Zwykła Java, bez zależności od frameworka.
Record (record Record(RecordClass type, Integer value, byte[] raw))
typeto klasa rekordu,valueto waga (tylko dlaOK, w pozostałych przypadkachnull).rawto dokładne bajty przesłane przez sterownik dla danego rekordu, razem z końcowym CRLF.- Dla rekordu, który przekroczył limit długości,
rawto dokładniemaxpierwszych bajtów. toString()wypisujerawjako hex orazhumanRawjako tekst w UTF-8 Przykład:Record[type=OK, value=42, raw=[34 32 0D 0A] humanRaw="42\r\n"].
RecordParser
new RecordParser(maxRecordBytes), potemparse(buf, off, len, consumer). Konsument dostaje każdy ukończony rekord.- Rekord kończy się sekwencją
CR LF. Rekord może być rozcięty między porcjami TCP, parser trzyma stan między wywołaniami. - Gdy linia osiąga
maxRecordBytes, parser emituje rekordNON_DIGIT(raw= pierwszemaxbajtów). Potem odrzuca resztę linii aż do następnego CRLF, bez ponownego raportowania. - W serwisie
max-record-bytes= 512 (konfigurowalne).
RecordClassifier klasyfikuje linię (bez CRLF) do RecordClass:
| Klasa | Znaczenie |
|---|---|
OK |
1–6 cyfr ASCII, bez znaku. Wartość 0–999999. |
EMPTY_LINE |
pusta linia (samo CRLF) |
NEGATIVE |
zaczyna się od - (reszta ignorowana, wartość odrzucona) |
OVERWEIGHT |
więcej niż 6 znaków i bez - (czyli ≥ 1 000 000, ponad 100 t, uznajemy za błąd). Sprawdzane przed walidacją cyfr. |
NON_DIGIT |
znak niebędący cyfrą albo linia dłuższa niż limit parsera |
Szczegóły pakietów z MOXA: protokol-moxa.md.
C. Serwis nasłuchiwacza połączeń TCP (tcp-service)¶
Minimalna aplikacja Grails 8cd.
TcpListenerService (SmartLifecycle)
- Otwiera
ServerSocketnaweight.port(domyślnie 14002) przy starcie aplikacji. - Obsługuje jedno połączenie naraz. Nowy klient zamyka poprzednie połączenie i je przejmuje.
- Ustawia
SO_KEEPALIVEi timeout odczytuweight.read-timeout-ms(60 s). Jeśli waga milczy dłużej, połączenie jest zamykane. - Przy zatrzymaniu aplikacji zamyka gniazdo serwera i aktualne połączenie.
- Bajty przekazuje do
WeightService, sam niczego nie parsuje.
WeightService
handle(InputStream)czyta strumień i podaje go doRecordParser.- Każdy rekord, także niepoprawny, zapisuje jako najnowszy
WeightReading(rekord + czas odebraniareceivedAt). Niepoprawny rekord nadpisuje poprzedni dobry odczyt. isStale(reading)zwracatrue, gdy odczyt jest starszy niżweight.max-age-ms.- Odczyt przeżywa rozłączenie wagi, ale po
max-age-msstaje się nieświeży.
WeightController: GET /weight
Odpowiedź to mała strona HTML, zgodna z tym co już przyjmuje Apollo.
Świeży, poprawny odczyt, status 200:
W pozostałych przypadkach status 503 i strona błędu. Stara wartość nigdy nie jest zwracana.
data-code |
Kiedy |
|---|---|
NO_DATA |
od startu nie odebrano żadnego rekordu |
STALE |
ostatni rekord starszy niż weight.max-age-ms |
INVALID |
ostatni rekord nie był poprawną wagą (np. NEGATIVE, OVERWEIGHT) |
Kolejność sprawdzania: NO_DATA, potem STALE, potem INVALID.
StatusController: GET /status (tylko GET, nagłówek Cache-Control: no-store)
Stan połączenia z wagą jako JSON, dla panelu admin.
Endpoint zawsze zwraca status 200, bo brak wagi jest stanem, a nie błędem.
Pola bez danych mają wartość null.
{"connected":true,"peer":"10.0.0.5:51234","connectedSince":"2026-11-02T07:40:00.100Z",
"lastRecordAt":"2026-11-02T07:47:36.239Z","lastRecordType":"OK","lastValue":37900,"stale":false}
| Pole | Znaczenie |
|---|---|
connected |
czy waga jest teraz połączona z bramką |
peer |
adres klienta w postaci host:port, null bez połączenia |
connectedSince |
czas nawiązania obecnego połączenia |
lastRecordAt |
czas odebrania ostatniego rekordu, także niepoprawnego |
lastRecordType |
klasa ostatniego rekordu, np. OK albo NEGATIVE |
lastValue |
waga z ostatniego rekordu, null dla rekordu niepoprawnego |
stale |
czy ostatni rekord jest starszy niż weight.max-age-ms, null przed pierwszym rekordem |
Ostatni rekord pozostaje w odpowiedzi po rozłączeniu wagi.
Konfiguracja (application.yml):
| Klucz | Domyślnie | Opis |
|---|---|---|
weight.port |
14002 |
port nasłuchu TCP (w środowisku test: 0, czyli port losowy) |
weight.max-record-bytes |
512 |
limit długości jednej linii |
weight.read-timeout-ms |
60000 |
timeout ciszy od wagi |
weight.max-age-ms |
5000 |
maksymalny wiek odczytu serwowanego przez HTTP |
D. Mock (mock)¶
Symulator wagi, czyli klient TCP, który łączy się z tcp-service tak jak MOXA.
Moduł to biblioteka Java z klasą ScaleMock oraz CLI ScaleMockCli.
admin używa ScaleMock jako zależności, a testy integracyjne tcp-service wysyłają nim dane do prawdziwej aplikacji.
ScaleMock (AutoCloseable)
new ScaleMock(host, port)albonew ScaleMock(port)łączy się z127.0.0.1. Połączenie nie jest zamykane przez mocka samodzielnie.sendWeight(int)wysyła liczbę z końcowym CRLF.sendLine(String)wysyła dowolną linię z CRLF, np. rekord niepoprawny.sendRaw(String)wysyła tekst bez CRLF, czyli rekord niedokończony.sendChunks(pauseMs, chunks...)wysyła porcje z przerwą, żeby sprawdzić rekord rozcięty między porcjami TCP.startStreaming(periodMs, weights)istopStreaming()wysyłają wagę w stałym odstępie z osobnego wątku.isOpen()iisClosedByGateway()pozwalają sprawdzić, czy bramka zamknęła połączenie, np. po przekroczeniuweight.read-timeout-msalbo przejęciu przez nowego klienta.- Zapisy są synchronizowane, więc ręczne wysyłanie można mieszać ze strumieniem.
ScaleMockCli
Bez periodMs odstęp wynosi 1000 ms, a bez weight mock losuje wagę z zakresu 0–100000.
Opis uruchamiania jest na stronie Uruchamianie i testowanie.
Test jednostkowy: ScaleMockTest.
E. Integracje, dokumentacje i wdrożenia¶
Testy:
- Jednostkowe
weight-protocol:RecordParserTest(m.in.rawper rekord przy wielu rekordach w porcji, rekord rozcięty między porcjami, przepełnienie),RecordTest. - Jednostkowe
weight-protocol: takżeRecordClassifierTest. - Jednostkowe
tcp-service:WeightServiceSpec,WeightControllerSpec,StatusControllerSpec,TcpListenerServiceSpec. - Jednostkowe
admin:GatewayControllerSpec,GatewayStatusServiceSpec,MockScaleControllerSpec,MockScaleServiceSpec. - Jednostkowe
mock:ScaleMockTest. - Integracyjne
tcp-service:WeightEndpointSpec, aplikacja na losowym porcie i dane zScaleMock. - Integracyjne
admin:WeightGatewaySpec, Geb z kontenerem Dockera.
Polecenia testów opisuje strona Uruchamianie i testowanie.
Wdrożenie:
Dockerfilebuduje obrazytcp-serviceiadmin, adocker-compose.ymlw katalogu głównym to stack lokalny.- Pipeline TeamCity (check, publish, deploy) opisuje strona Wdrożenie.
- Ustawienia aplikacji opisuje strona Konfiguracja.
Do zrobienia:
- Integracja z
apollo-docker - Przygotowanie sieci i serwera (zadania DEV)
- Testy akceptacyjne z prawdziwą wagą
F. Panel administracyjny (admin)¶
Aplikacja Grails dla testerów i supportu.
Ma dwie strony: status połączenia z MOXA i symulator wagi.
Nie ma logowania, więc na produkcji powinna być dostępna tylko z VPN.
Baza H2 jest skonfigurowana, ale panel niczego w niej nie zapisuje.
Port HTTP to 8081.
Status połączenia z MOXA (/gateway)
Strona odpytuje GET /status w tcp-service i pokazuje, czy waga jest połączona.
Przy połączeniu widać adres klienta i czas nawiązania połączenia.
Widać też ostatni rekord: czas, klasę, wagę i informację, czy odczyt jest świeży.
Gdy tcp-service nie odpowiada, strona pokazuje stan "Gateway unreachable" z przyczyną.
Strona przeładowuje się sama co 3 sekundy.
Symulator wagi (/mockScale)
Strona steruje jednym symulowanym połączeniem (MockScaleService, oparty o ScaleMock).
Stan jest w pamięci i znika po restarcie panelu.
Strona działa tylko, gdy mock.enabled ma wartość true, a w środowisku production każda akcja zwraca 404 (MockScaleInterceptor).
| Sekcja | Działanie |
|---|---|
| Connection | połączenie z bramką, domyślnie mock.gateway.host i mock.gateway.port, oraz rozłączenie |
| Streaming | wysyłanie wagi co periodMs (minimum 10 ms), stała waga albo losowa gdy pole jest puste |
| Send once | pojedyncza waga z zakresu 0–999999 |
| Presety | rekordy do testów błędów, tabela poniżej |
| Preset | Wysyłane dane | Oczekiwany efekt w GET /weight |
|---|---|---|
EMPTY_LINE |
samo CRLF | INVALID |
NEGATIVE |
-12 |
INVALID |
NON_DIGIT |
12a |
INVALID |
OVERWEIGHT |
1234567 |
INVALID |
TOO_LONG |
1000 znaków x |
INVALID (rekord przekroczył limit) |
PARTIAL |
12 bez CRLF |
bez zmiany, rekord czeka na koniec linii |
Błędy połączenia i niepoprawne dane wracają jako komunikat nad formularzem, a przy błędzie zapisu mock rozłącza się sam.
Konfiguracja panelu jest na stronie Konfiguracja.
Ostatnia zmiana: 2026-11-13 · Dariusz Bakowski
Zbudowano: 2026-11-20 10:32 UTC · wersja 1.0.0 · rewizja: 19fcdc12e