# egov/rabbitmq-classes v1.1.27 — ανάλυση (2026-08-06)

Πηγή: κλώνος του `gitlab.skel.iit.demokritos.gr/egovapp/egovrabbitmqclasses.git` στο
commit `03ac62f` (= το pin του composer.lock στο ms.gov_ked skeleton). 14 αρχεία source,
proprietary license, PHP ^8.1, Laravel >=8.75. Auto-discovered provider καταχωρεί μόνο το
artisan command `rabbitmq:read`.

> **Επαληθεύτηκε εκτελεστικά (2026-08-06):** όλα τα παρακάτω επιβεβαιώθηκαν τρέχοντας τον
> κώδικα σε αυτό το repo — ping και submit_beveosi πέρασαν end-to-end από τον broker, και το
> `tests/Feature/InterpreterIntegrationTest.php` τα κλειδώνει χωρίς broker. Δεν είναι πλέον
> ανάγνωση κώδικα, είναι μετρημένη συμπεριφορά.

## Wire format — ΛΥΘΗΚΕ

**Δεν είναι hash.** Το request body είναι απλό string:

```
command_name|http_build_query($params, '', null, PHP_QUERY_RFC3986)
```

π.χ. `submit_beveosi|afm=012345678&kae=00345&synypochreoi%5B0%5D%5Bafm%5D=...`

- Nested arrays δουλεύουν κανονικά (bracket notation του http_build_query / parse_str) —
  άρα συνυπόχρεοι/δόσεις/ΚΑΕ rows περνάνε ως έχουν.
- Αποκωδικοποίηση στο MS (`RabbitMQMessageInterpreter::loadMessageInfo`):
  `explode('|')` → `parse_url('http://bff.egov.gr?'.$arr[1])` → `parse_str`.
- Params με πρόθεμα `_` = «internal params» (κρατιούνται χωριστά, δεν πάνε στο
  3rd-party API στα api_commands). **Δεν υπάρχει πεδίο `token`** στο envelope — ό,τι
  auditUserId/IP θέλουμε, το ζητάμε ως κανονικά (ή `_`) params. Το δικό μας
  `{command, params, token}` JSON envelope ήταν υπόθεση — το token δεν υφίσταται.
- Whitelist ημερομηνιών (`DATE_TYPE_PARAMETERS`: date, date_from, date_to, created_at,
  updated_at κ.ά.) περνάει από `Carbon::parse()->toDateString()` — προσοχή αν ονομάσουμε
  δικό μας πεδίο έτσι, θα «κανονικοποιηθεί» εν αγνοία μας.
- **Response**: ό,τι επιστρέψει το `ICommand::execute()` δημοσιεύεται αυτούσιο ως reply
  body. Πρότυπο (PingCommand του skeleton): `return json_encode($rabbitMQResponse);`.

## Consumer (MS side)

`artisan rabbitmq:read` → `RabbitMQJob::dispatch()` (με `QUEUE_CONNECTION=sync` τρέχει
inline, αέναο loop). Μέσα στο `handle()`:

- Σύνδεση από `config('microservices.{ms_name}.host|port|user|password|vhost')` με
  defaults localhost/5672/guest/guest/`/` όταν λείπουν.
- `queue_declare(queue, passive=false, durable=false, exclusive=false, auto_delete=false)`
  — **non-durable**, ενώ το δικό μας M1 worker δηλώνει durable. Σε κοινό broker αυτό
  σκάει PRECONDITION_FAILED — κατά το porting ευθυγραμμιζόμαστε με το δικό τους.
- `basic_qos(null, 1, null)`, manual ack.
- Reply: publish στο default exchange με routing key = `reply_to`, `correlation_id`
  echoed. Χωρίς guard για null reply_to (publish σε '' routing key = χάνεται αβλαβώς —
  δεν υπάρχει ο self-loop κίνδυνος του δικού μας fallback).
- **`$req->ack()` πάντα, σε finally** — και σε αποτυχία· poison messages καταναλώνονται
  αφού γίνει μία προσπάθεια reply. (Το δικό μας M1 έκανε nack χωρίς requeue — ίδιο
  τελικό αποτέλεσμα, διαφορετικός μηχανισμός.)

## Dispatch

`RabbitMQMessageInterpreter::process()`:

- `api_commands` (config/rabbit_commands.php): για proxy σε **REST APIs** — φτιάχνει
  instance του δηλωμένου `httpClient` class και καλεί
  `makeCallWithWait($command, $serviceParamsArray, $internalParamsArray, ...)`.
  Το `APIMapping` (σχολιασμένο στο skeleton) δείχνει τη λογική: command → endpoint +
  αντιστοίχιση params. **Δεν ταιριάζει στο SOAP μας ως έχει** — αν ο Δημόκριτος θέλει
  τα δικά μας ως api_commands, ο «httpClient» μας θα είναι wrapper πάνω στον
  KedeProgressClient. Αλλιώς μένουμε σε plain commands (όπως το PingCommand τους).
- `commands` (plain): `new $commandClass()` → `execute($this->paramsKeyValueArray)` —
  ακριβώς το δικό μας ICommand μοντέλο.
- Άγνωστο command → επιστρέφει `json_encode(['error' => ...])` (όχι RabbitMQResponse
  shape). Exceptions μέσα σε command → `json_encode('Error occurred ...')` string.

## BFF side (για το dev bridge μας)

`RpcClient::callWithResponse(RabbitMQRequest)`:

- Anonymous exclusive callback queue, `correlation_id = uniqid()`, publish στο routing
  key του MS από `config('microservices.{ms}.routing_key')`, blocking wait μέχρι
  να έρθει απάντηση με ίδιο correlation_id, `RabbitMQResponse->deserialize($json)`.
- Σύνδεση από `config('rabbitmq.host|port|user|password')` — ξεχωριστό config file
  στο BFF (όχι microservices.php).

`RabbitMQRequest`: κατασκευάζεται με `(command, params, ['ms' =>, 'module' =>,
'definitions' => SomeDefinitions::class])`. Το definitions class (ανά **ms.module** —
εδώ υλοποιείται το «module» beveosi_ofeilwn!) ορίζει `ALL_PARAMETERS` και
`COMMAND_PARAMS_MAPPING`, με modes validation loose/minimum/strict. **Αυτό είναι το
αντικείμενο του deliverable «στείλτε μας πεδία/params»: ουσιαστικά γράφουμε εμείς το
περιεχόμενο του definitions class για το gov_ked.beveosi_ofeilwn.**

## Response shape — ΔΙΟΡΘΩΣΕΙΣ στο δικό μας mirror/contract

Το πραγματικό JSON (json_encode των public properties του `RabbitMQResponse`, με σειρά
δήλωσης):

```json
{
  "data": ...,
  "pagination": [],
  "extraData": [],
  "errors": [],
  "warnings": [],
  "messages": [],
  "status": 1,
  "type": "single"
}
```

Διαφορές από το `App\Messaging\RabbitMQResponse` και το `docs/message-contract.md`:

1. **`status` είναι int-backed enum**: OK=1, WARNING=2, ERROR=3, **BUSINESS_ERROR=4**
   (εμείς έχουμε strings OK/ERROR και μόνο 2 τιμές).
2. **`type` είναι lowercase**: `single` / `list` / **`lookup`** (εμείς SINGLE_ITEM/LIST·
   το LOOKUP είναι χρήσιμο για το μελλοντικό get_lookup_values).
3. **Σειρά κλειδιών** διαφορετική από τη δική μας (data, pagination, extraData, errors,
   warnings, messages, status, type).
4. Δεν υπάρχει `token` στο inbound — βλ. παραπάνω.

Το contract που στείλαμε στο BFF θέλει επικαιροποίηση σε αυτά τα 4 σημεία.

## Quirks / ρίσκα που είδαμε στον κώδικα

- `paramsKeyValueArray` είναι **αδήλωτο dynamic property** στον interpreter — δουλεύει
  σε PHP 8.1, deprecated σε 8.2+. Ένας ακόμα λόγος που το Laravel 10 / PHP 8.1 pin
  είναι σωστός.
- Command **χωρίς** `|` (σκέτο `ping`): το `paramsKeyValueArray` δεν αρχικοποιείται
  ποτέ → TypeError → γυρνάει error string. Με `ping|` (κενό query) δουλεύει. Το δικό
  μας dev bridge πρέπει πάντα να στέλνει το `|`.
- Μεγάλα payloads: `parse_str` υπόκειται σε `max_input_vars` (default 1000) — πολλά
  installment/KAE rows ή αρχεία (τα attachments ταξιδεύουν ως `file[N][data]` base64
  μέσα στο query string, όπως δείχνει ο truncation κώδικας του logging) μπορεί να το
  χτυπήσουν. Να ελεγχθεί το όριο στο PHP config του worker.
- `deserialize()` στο BFF: αν το MS γυρίσει τα «γυμνά» error strings του interpreter,
  το reflection loop δεν βρίσκει properties και επιστρέφει default (OK!) response —
  δικό τους θέμα, αλλά εξηγεί γιατί ΠΟΤΕ δεν πρέπει τα δικά μας commands να αφήσουν
  exception να βγει ως σκέτο string· πάντα επιστρέφουμε πλήρες RabbitMQResponse JSON.
- `queue_declare` non-durable + ack-always: μηνύματα χάνονται σε restart του broker
  και poison messages δεν ξανα-παραδίδονται — συμπεριφορά της υποδομής τους, όχι δική
  μας απόφαση.

## Συνέπειες για το porting (M1 κώδικας → ms.gov_ked)

1. Ο `EgovHashMessageCodec` placeholder μας μπορεί πλέον να γραφτεί και αυτόνομα
   (format γνωστό), αλλά στο gov_ked ο consumer/dispatch έρχεται από το package —
   τα δικά μας `RabbitConsumeCommand`/`MessageCodec`/`Envelope` αντικαθίστανται.
2. Τα command classes μας μεταφέρονται σχεδόν αυτούσια: αλλαγή imports σε
   `Egov\RabbitmqClasses\...`, `execute()` επιστρέφει `json_encode($response)`,
   προσαρμογή στα σωστά enums (int status, lowercase type).
3. Ο έλεγχος `bff:publish`/`RpcPublisher` του dev bridge πρέπει να μιμείται τον
   RpcClient (uniqid correlation, format `command|query`, πάντα με `|`).
4. Validation παραμένει δική μας ευθύνη μέσα στα commands (το «strict mode» του
   RabbitMQRequest ελέγχει μόνο παρουσία κλειδιών στο BFF, όχι τύπους/κανόνες).
