Przejdź do treści

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))

  • type to klasa rekordu, value to waga (tylko dla OK, w pozostałych przypadkach null).
  • raw to dokładne bajty przesłane przez sterownik dla danego rekordu, razem z końcowym CRLF.
  • Dla rekordu, który przekroczył limit długości, raw to dokładnie max pierwszych bajtów.
  • toString() wypisuje raw jako hex oraz humanRaw jako tekst w UTF-8 Przykład: Record[type=OK, value=42, raw=[34 32 0D 0A] humanRaw="42\r\n"].

RecordParser

  • new RecordParser(maxRecordBytes), potem parse(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 rekord NON_DIGIT (raw = pierwsze max bajtó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 ServerSocket na weight.port (domyślnie 14002) przy starcie aplikacji.
  • Obsługuje jedno połączenie naraz. Nowy klient zamyka poprzednie połączenie i je przejmuje.
  • Ustawia SO_KEEPALIVE i timeout odczytu weight.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 do RecordParser.
  • Każdy rekord, także niepoprawny, zapisuje jako najnowszy WeightReading (rekord + czas odebrania receivedAt). Niepoprawny rekord nadpisuje poprzedni dobry odczyt.
  • isStale(reading) zwraca true, gdy odczyt jest starszy niż weight.max-age-ms.
  • Odczyt przeżywa rozłączenie wagi, ale po max-age-ms staje 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:

<span id="weight" data-received-at="2026-11-02T07:47:36.239Z">37900</span>

W pozostałych przypadkach status 503 i strona błędu. Stara wartość nigdy nie jest zwracana.

<p id="error" data-code="STALE">The last reading is older than 5 s.</p>
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) albo new ScaleMock(port) łączy się z 127.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) i stopStreaming() wysyłają wagę w stałym odstępie z osobnego wątku.
  • isOpen() i isClosedByGateway() pozwalają sprawdzić, czy bramka zamknęła połączenie, np. po przekroczeniu weight.read-timeout-ms albo przejęciu przez nowego klienta.
  • Zapisy są synchronizowane, więc ręczne wysyłanie można mieszać ze strumieniem.

ScaleMockCli

./gradlew :mock:run --args="<host> <port> [periodMs] [weight]"

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. raw per rekord przy wielu rekordach w porcji, rekord rozcięty między porcjami, przepełnienie), RecordTest.
  • Jednostkowe weight-protocol: także RecordClassifierTest.
  • 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 z ScaleMock.
  • Integracyjne admin: WeightGatewaySpec, Geb z kontenerem Dockera.

Polecenia testów opisuje strona Uruchamianie i testowanie.

Wdrożenie:

  • Dockerfile buduje obrazy tcp-service i admin, a docker-compose.yml w 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