server.py

#!/usr/bin/env python3
"""
ASTM LIS2-A2 Mock Server for OpenELIS Analyzer Testing

This server simulates an ASTM-compatible laboratory analyzer for testing
the OpenELIS analyzer field mapping feature.

Reference Documents:
- specs/004-astm-analyzer-mapping/research.md Section 1 (ASTM Protocol)
- specs/004-astm-analyzer-mapping/spec.md FR-001, FR-002

ASTM LIS2-A2 Protocol Overview:
1. Client sends ENQ (0x05) to initiate communication
2. Server responds with ACK (0x06) if ready
3. Client sends data frames: <STX><FN><data><ETX/ETB><checksum><CR><LF>
4. Server ACKs each frame
5. Client sends EOT (0x04) to end transmission
6. Roles can reverse for bidirectional communication

Usage:
    python server.py [--port PORT] [--analyzer-type TYPE]

Environment Variables:
    ASTM_PORT: Server port (default: 5000)
    ANALYZER_TYPE: Analyzer type from fields.json (default: HEMATOLOGY)
    RESPONSE_DELAY_MS: Simulated response delay in milliseconds (default: 100)
"""

import select
import re
import socket
import threading
import uuid
import json
import os
import sys
import time
import logging
import argparse
from typing import Optional, Dict, List, Any

from protocols.astm_handler import generate_astm_message, ASTMHandler
from protocols.hl7_handler import HL7Handler, generate_oru_r01
from protocols.mllp_listener import MLLPProtocolHandler
from protocols.serial_handler import SerialHandler, send_astm_over_serial
from protocols.file_handler import FileHandler
from push import push_hl7_http, push_astm_to_destination
from api import start_api_server

# Optional: template loader for HL7 --hl7 push and /simulate/hl7 API (Abbott, etc.)
try:
    from template_loader import TemplateLoader
    HAS_HL7_SIM = True
except ImportError:
    TemplateLoader = None
    HAS_HL7_SIM = False

# Configure logging
logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(levelname)s - %(message)s'
)
logger = logging.getLogger(__name__)

# ASTM LIS2-A2 Control Characters
ENQ = b'\x05'  # Enquiry - Start transmission
ACK = b'\x06'  # Acknowledge - Positive response
NAK = b'\x15'  # Negative Acknowledge
EOT = b'\x04'  # End of Transmission
STX = b'\x02'  # Start of Text (frame start)
ETX = b'\x03'  # End of Text (frame end with checksum)
ETB = b'\x17'  # End of Text Block (intermediate frame)
CR = b'\x0D'   # Carriage Return
LF = b'\x0A'   # Line Feed
VT = b'\x0B'   # MLLP Start Block
FS = b'\x1C'   # MLLP End Block

# Server Configuration
DEFAULT_PORT = 5000
DEFAULT_ANALYZER_TYPE = 'HEMATOLOGY'
DEFAULT_RESPONSE_DELAY_MS = 100

# CLSI LIS1-A Timeout Requirements
ESTABLISHMENT_TIMEOUT = 15  # seconds - ENQ response timeout
FRAME_ACK_TIMEOUT = 15      # seconds - Frame ACK timeout  
RECEIVER_TIMEOUT = 30       # seconds - Receiver waiting for frame/EOT
SOCKET_TIMEOUT = 60         # seconds - Overall socket timeout (keep for safety)
MAX_CONNECTIONS = 10

# Restricted characters per CLSI LIS1-A 8.6
RESTRICTED_CHARS = [
    b'\x01',  # SOH
    b'\x02',  # STX
    b'\x03',  # ETX
    b'\x04',  # EOT
    b'\x05',  # ENQ
    b'\x06',  # ACK
    b'\x10',  # DLE
    b'\x15',  # NAK
    b'\x16',  # SYN
    b'\x17',  # ETB
    b'\x0A',  # LF (only allowed as last char of frame)
    b'\x11',  # DC1
    b'\x12',  # DC2
    b'\x13',  # DC3
    b'\x14',  # DC4
]


class ASTMProtocolHandler:
    """Handles ASTM LIS2-A2 protocol communication for a single client.

    Supports both legacy fields.json and template-driven ASTM generation.
    When astm_template is provided (or resolved from local_port + port_to_template),
    field query responses and data generation use ASTMHandler.generate() for
    spec-compliant messages (GeneXpert, etc.).
    """

    def __init__(self, conn: socket.socket, addr: tuple, fields_config: Dict,
                 response_delay_ms: int = DEFAULT_RESPONSE_DELAY_MS,
                 astm_template: Optional[Dict] = None,
                 local_port: Optional[int] = None,
                 port_to_template: Optional[Dict[int, str]] = None):
        self.conn = conn
        self.addr = addr
        self.fields_config = fields_config
        self.response_delay_ms = response_delay_ms
        if port_to_template and local_port is not None:
            template_name = port_to_template.get(local_port) or os.environ.get("ASTM_TEMPLATE")
            self.astm_template = _load_template(template_name) if template_name else None
            if self.astm_template and template_name:
                name = self.astm_template.get("analyzer", {}).get("name", template_name)
                logger.info("Connection on port %s: using template %s (%s)", local_port, template_name, name)
        else:
            self.astm_template = astm_template
        self.frame_number = 0
        self.last_accepted_frame = 0  # Track last accepted frame number per CLSI LIS1-A
        self.retransmit_count = 0  # Track retransmissions per CLSI LIS1-A
        self.received_data: List[bytes] = []
        self.received_orders: List[Dict[str, str]] = []  # inbound LIS orders awaiting result push
        self.running = True
        
    def handle(self):
        """Main handler loop for client connection."""
        logger.info(f"Client connected: {self.addr}")
        self.conn.settimeout(SOCKET_TIMEOUT)

        # If template has proactive_enq, send ENQ immediately (like real
        # GeneXpert which has queued results). This creates contention if the
        # client also sends ENQ — matching real instrument behavior per
        # CLSI LIS1-A §8.2.7.1.
        if self.astm_template and self.astm_template.get('astm_config', {}).get('proactive_enq'):
            logger.info(f"[PROACTIVE_ENQ] Sending ENQ to {self.addr} (instrument has data)")
            self._send(ENQ)
            try:
                response = self._receive_byte()
                if response == ACK:
                    # Client accepted — send our data
                    self._send_frames_from_template()
                elif response == ENQ:
                    # CONTENTION: both sides sent ENQ. Yield to client — when the
                    # LIS has active work (orders), it takes priority over our
                    # queued results. ACK the client's ENQ so it proceeds to send
                    # its frames; the normal receive loop processes them and
                    # send_order_response pushes results back. The template's
                    # proactive push is forfeit for this connection.
                    logger.info(f"[PROACTIVE_ENQ] Contention with {self.addr}, yielding to client")
                    self._send(ACK)
                # Fall through to normal receive loop regardless
            except socket.timeout:
                logger.debug(f"[PROACTIVE_ENQ] No response, entering receive mode")

        try:
            while self.running:
                data = self._receive_byte()
                if not data:
                    break
                    
                if data == ENQ:
                    self._handle_enq()
                elif data == EOT:
                    self._handle_eot()
                elif data == STX:
                    self._handle_frame()
                else:
                    logger.warning(f"Unexpected byte received: {data.hex()}")
                    
        except socket.timeout:
            logger.info(f"Client timeout: {self.addr}")
        except ConnectionResetError:
            logger.info(f"Client disconnected: {self.addr}")
        except Exception as e:
            logger.error(f"Error handling client {self.addr}: {e}")
        finally:
            self._cleanup()
            
    def _receive_byte(self) -> Optional[bytes]:
        """Receive a single byte from client."""
        try:
            return self.conn.recv(1)
        except socket.timeout:
            return None
            
    def _receive_until(self, terminator: bytes, max_length: int = 4096) -> bytes:
        """Receive data until terminator sequence."""
        data = b''
        while len(data) < max_length:
            byte = self._receive_byte()
            if not byte:
                break
            data += byte
            if data.endswith(terminator):
                break
        return data
        
    def _send(self, data: bytes):
        """Send data to client with optional delay."""
        if self.response_delay_ms > 0:
            time.sleep(self.response_delay_ms / 1000.0)
        self.conn.send(data)
        
    def _handle_enq(self):
        """Handle ENQ (enquiry) - client wants to send data."""
        logger.debug(f"Received ENQ from {self.addr}")
        # Per CLSI LIS1-A: Must respond within establishment timeout
        self._send(ACK)
        logger.debug(f"Sent ACK to {self.addr}")
        
    def _handle_eot(self):
        """Handle EOT (end of transmission)."""
        logger.debug(f"Received EOT from {self.addr}")
        # Process any received data
        if self.received_data:
            self._process_received_data()
        # Connection remains open for potential next transmission
        
    def _handle_frame(self):
        """Handle incoming ASTM data frame."""
        # Read frame content until ETX/ETB + checksum + CR + LF
        frame_data = self._receive_until(CR + LF)
        
        if not frame_data:
            logger.warning("Empty frame received")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
            
        # Parse frame: <FN><data><ETX/ETB><checksum>
        if len(frame_data) < 4:  # Minimum: FN + ETX + checksum(2) + CRLF
            logger.warning(f"Frame too short: {len(frame_data)}")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
            
        # Extract frame content (between STX and checksum)
        # Frame number is first byte after STX
        frame_num_bytes = frame_data[0:1]
        
        # Extract frame number (ASCII digit '1'-'7')
        try:
            frame_num_char = frame_num_bytes.decode('ascii', errors='strict')
            if not frame_num_char.isdigit():
                logger.warning(f"Invalid frame number: {frame_num_char}")
                self._send(NAK)
                self.retransmit_count += 1
                if self.retransmit_count >= 6:
                    logger.error("Aborting: Frame retransmitted 6 times without success")
                    self._send(EOT)
                    self.running = False
                return
            
            frame_num = int(frame_num_char)
        except (UnicodeDecodeError, ValueError) as e:
            logger.warning(f"Invalid frame number encoding: {e}")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
        
        # Validate frame number per CLSI LIS01-A2 §6.3.2.1:
        # Frame numbers 0-7, begin at 1, increment by 1, wrap 7→0.
        if self.last_accepted_frame == 0:
            # First frame — accept any valid frame number (0-7)
            if frame_num < 0 or frame_num > 7:
                logger.warning(f"Invalid frame number range: {frame_num} (must be 0-7)")
                self._send(NAK)
                self.retransmit_count += 1
                if self.retransmit_count >= 6:
                    logger.error("Aborting: Frame retransmitted 6 times without success")
                    self._send(EOT)
                    self.running = False
                return
        else:
            # Subsequent frames: must be same as last accepted OR one higher (mod 8)
            expected_frame = (self.last_accepted_frame + 1) % 8
            if frame_num != self.last_accepted_frame and frame_num != expected_frame:
                logger.warning(f"Frame number mismatch: expected {expected_frame} or {self.last_accepted_frame}, got {frame_num}")
                self._send(NAK)
                self.retransmit_count += 1
                if self.retransmit_count >= 6:
                    logger.error("Aborting: Frame retransmitted 6 times without success")
                    self._send(EOT)
                    self.running = False
                return
        
        # Find ETX or ETB position
        etx_pos = frame_data.find(ETX)
        etb_pos = frame_data.find(ETB)
        
        if etx_pos == -1 and etb_pos == -1:
            logger.warning("No frame terminator found")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
            
        term_pos = etx_pos if etx_pos != -1 else etb_pos
        content = frame_data[1:term_pos]
        
        # Validate message characters per CLSI LIS1-A 8.6
        if not self._validate_message_chars(content):
            logger.warning("Restricted characters found in message text")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
        
        # Extract checksum (2 hex digits after ETX/ETB)
        checksum_start = term_pos + 1
        if len(frame_data) < checksum_start + 2:
            logger.warning("Incomplete checksum in frame")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
        
        checksum_str = frame_data[checksum_start:checksum_start+2].decode('ascii', errors='ignore')
        
        # Calculate expected checksum: sum of bytes from frame number to ETX, mod 256
        checksum_data = frame_data[0:term_pos+1]  # FN + content + ETX
        calculated_checksum = sum(checksum_data) % 256
        expected_checksum_str = f'{calculated_checksum:02X}'
        
        if checksum_str.upper() != expected_checksum_str:
            logger.warning(f"Checksum mismatch: expected {expected_checksum_str}, got {checksum_str}")
            self._send(NAK)
            self.retransmit_count += 1
            if self.retransmit_count >= 6:
                logger.error("Aborting: Frame retransmitted 6 times without success")
                self._send(EOT)
                self.running = False
            return
        
        # Frame is valid - reset retransmit counter and update last accepted frame
        self.retransmit_count = 0
        self.last_accepted_frame = frame_num
        
        logger.debug(f"Received frame {frame_num}: {content[:50]}...")
        self.received_data.append(content)
        self._send(ACK)
        
    def _process_received_data(self):
        """Process accumulated received data."""
        logger.info(f"[MESSAGE] Processing {len(self.received_data)} frames from {self.addr}")
        
        # Detect query type before processing/clearing data.
        # - Field query: header-only capability discovery (H + L)
        # - Results query: explicit Q-record request (H + Q + L)
        is_field_query = self._is_field_query()
        is_results_query = self._is_results_query()
        logger.debug(
            f"[MESSAGE] Query detection: is_field_query={is_field_query}, "
            f"is_results_query={is_results_query}"
        )
        
        for frame_idx, frame in enumerate(self.received_data, 1):
            try:
                decoded = frame.decode('utf-8', errors='replace')
                logger.debug(f"[MESSAGE] Frame {frame_idx}/{len(self.received_data)}: {decoded[:100]}")
                
                # Parse ASTM records (optional X|1|template_name| overrides port-based template)
                if decoded.startswith('X|'):
                    self._process_template_hint(decoded)
                elif decoded.startswith('H|'):
                    self._process_header(decoded)
                elif decoded.startswith('P|'):
                    self._process_patient(decoded)
                elif decoded.startswith('O|'):
                    self._process_order(decoded)
                elif decoded.startswith('R|'):
                    self._process_result(decoded)
                elif decoded.startswith('Q|'):
                    self._process_query_record(decoded)
                elif decoded.startswith('L|'):
                    self._process_terminator(decoded)
                    
            except Exception as e:
                logger.error(f"[MESSAGE] Error processing frame {frame_idx}: {e}", exc_info=True)
                
        # Snapshot orders before clearing for response dispatch
        orders_snapshot = list(self.received_orders)
        self.received_orders = []

        # Clear received data
        self.received_data = []

        # Respond to query / order if detected
        if is_results_query:
            logger.info(f"[MESSAGE] Results query detected from {self.addr}, sending template results")
            self.send_results_query_response()
        elif is_field_query:
            logger.info(f"[MESSAGE] Field query detected from {self.addr}, sending field list")
            self.send_field_query_response()
        elif orders_snapshot:
            logger.info(
                f"[ORDER_IN] {len(orders_snapshot)} order record(s) from {self.addr}, pushing results"
            )
            self.send_order_response(orders_snapshot)
        else:
            logger.debug(f"[MESSAGE] No query/order detected, no response needed")
        
    def _process_template_hint(self, record: str):
        """Process X (template hint) record: X|1|template_name| overrides port-based template."""
        parts = record.strip().split('|')
        if len(parts) >= 3 and parts[2].strip():
            name = parts[2].strip()
            t = _load_template(name)
            if t and t.get('protocol', {}).get('type') == 'ASTM':
                self.astm_template = t
                logger.info("Template hint: using %s", name)
            else:
                logger.warning("Template hint unknown or not ASTM: %s", name)

    def _process_header(self, record: str):
        """Process H (Header) record."""
        logger.info(f"Header record received: {record[:60]}...")
        
    def _process_patient(self, record: str):
        """Process P (Patient) record."""
        parts = record.split('|')
        patient_id = parts[3] if len(parts) > 3 else 'Unknown'
        logger.info(f"Patient record: ID={patient_id}")
        
    def _process_order(self, record: str):
        """Process O (Order) record. Tracks accession + requested test code for
        an inbound LIS order so send_order_response can echo a matching result.
        ASTM universal-test-id is field 5 (parts[4]); format `^^^TESTCODE` per
        LIS2-A2 §7.4.4."""
        parts = record.split('|')
        sample_id = parts[2] if len(parts) > 2 else ''
        test_universal_id = parts[4] if len(parts) > 4 else ''
        test_components = test_universal_id.split('^')
        test_code = test_components[3] if len(test_components) > 3 else ''
        logger.info(f"Order record: Sample={sample_id} Test={test_code}")
        if sample_id and test_code:
            self.received_orders.append({
                'sample_id': sample_id,
                'test_code': test_code,
            })
        
    def _process_result(self, record: str):
        """Process R (Result) record."""
        parts = record.split('|')
        if len(parts) >= 4:
            test_code = parts[2] if len(parts) > 2 else 'Unknown'
            value = parts[3] if len(parts) > 3 else ''
            unit = parts[4] if len(parts) > 4 else ''
            logger.info(f"Result record: {test_code} = {value} {unit}")
            
    def _process_query_record(self, record: str):
        """Process Q (ASTM query) record."""
        parts = record.split('|')
        sample_id = parts[2] if len(parts) > 2 else ""
        requested_tests = parts[4] if len(parts) > 4 else "ALL"
        logger.info(
            f"Query record: sample={sample_id or 'unknown'} tests={requested_tests or 'ALL'}"
        )
        
    def _process_terminator(self, record: str):
        """Process L (Terminator) record."""
        logger.debug("Message terminator received")
    
    def _is_field_query(self) -> bool:
        """Detect if received message is a field query request.
        
        Query is detected when:
        - Header (H) record is present
        - No explicit Q record
        - No Patient (P) or Order (O) records follow
        - Only header + terminator received
        """
        if not self.received_data:
            return False
        
        has_header = False
        has_patient_or_order = False
        has_query_record = False
        
        for frame in self.received_data:
            try:
                decoded = frame.decode('utf-8', errors='replace')
                if decoded.startswith('H|'):
                    has_header = True
                elif decoded.startswith('P|') or decoded.startswith('O|'):
                    has_patient_or_order = True
                elif decoded.startswith('Q|'):
                    has_query_record = True
            except:
                pass
        
        return has_header and not has_patient_or_order and not has_query_record

    def _is_results_query(self) -> bool:
        """Detect if received message is an ASTM results query (H + Q + L)."""
        if not self.received_data:
            return False

        has_header = False
        has_query_record = False
        has_patient_or_order = False

        for frame in self.received_data:
            try:
                decoded = frame.decode('utf-8', errors='replace')
                if decoded.startswith('H|'):
                    has_header = True
                elif decoded.startswith('Q|'):
                    has_query_record = True
                elif decoded.startswith('P|') or decoded.startswith('O|'):
                    has_patient_or_order = True
            except:
                pass

        return has_header and has_query_record and not has_patient_or_order
    
    def _validate_message_chars(self, content: bytes) -> bool:
        """Validate message text doesn't contain restricted characters per CLSI LIS1-A 8.6."""
        # LF is allowed as last character of frame, so check content without trailing LF
        content_to_check = content.rstrip(LF)
        for restricted in RESTRICTED_CHARS:
            if restricted in content_to_check:
                logger.warning(f"Restricted character found in message: {restricted.hex()}")
                return False
        return True
        
    def send_field_query_response(self):
        """Send available fields or a full template-based ASTM message in response to a query.

        When astm_template is set (via ASTM_TEMPLATE env var), generates a full
        spec-compliant ASTM message using ASTMHandler. This is the pull-based flow:
        bridge connects as client, mock responds with template-generated data.

        When no template is set, falls back to legacy field list response.
        """
        logger.info(f"[FIELD_QUERY] Sending response to {self.addr}")

        # Initiate transmission: send ENQ and wait for ACK
        logger.debug(f"[FIELD_QUERY] Sending ENQ to initiate response")
        self._send(ENQ)

        try:
            response = self._receive_byte()
            if response != ACK:
                logger.warning(f"[FIELD_QUERY] Did not receive ACK, got: {response.hex() if response else 'none'}")
                return
            logger.debug(f"[FIELD_QUERY] Received ACK, proceeding")
        except socket.timeout:
            logger.warning("[FIELD_QUERY] Timeout waiting for ACK")
            return

        if self.astm_template:
            # Template mode: generate full ASTM message and send as framed records
            logger.info(f"[FIELD_QUERY] Using template: {self.astm_template.get('analyzer', {}).get('name', 'unknown')}")
            try:
                message = ASTMHandler().generate(self.astm_template, use_seed=True)
                records = [r for r in message.strip().split('\n') if r.strip()]
                for i, record in enumerate(records):
                    if not self._send_frame(record.strip()):
                        logger.warning(f"[FIELD_QUERY] Send failed at record {i+1}/{len(records)}")
                        break
                logger.info(f"[FIELD_QUERY] Sent {len(records)} template records to {self.addr}")
            except Exception as e:
                logger.error(f"[FIELD_QUERY] Template generation failed: {e}", exc_info=True)
                # Fall through to EOT
        else:
            # Legacy mode: send field list from fields.json
            header_record = f"H|\\^&|||MockAnalyzer^ASTM-Mock^1.0|||||||LIS2-A2"
            self._send_frame(header_record)

            frame_seq = 1
            analyzer_type = os.getenv('ANALYZER_TYPE', DEFAULT_ANALYZER_TYPE)
            fields = self.fields_config.get(analyzer_type, [])

            if not fields and self.fields_config:
                analyzer_type = list(self.fields_config.keys())[0]
                fields = self.fields_config[analyzer_type]

            logger.info(f"[FIELD_QUERY] Sending {len(fields)} fields for {analyzer_type}")

            for field in fields:
                field_name = field.get('name', 'Unknown')
                display_name = field.get('displayName', field_name)
                field_type = field.get('type', 'NUMERIC')
                unit = field.get('unit', '')
                astm_ref = field.get('astmRef', f'^^^{field_name}')

                if display_name != field_name and '^' not in astm_ref:
                    test_id = f"{astm_ref}^{display_name}"
                else:
                    test_id = astm_ref

                record = f"R|{frame_seq}|{test_id}||{unit}|||{field_type}"
                if not self._send_frame(record):
                    logger.warning(f"[FIELD_QUERY] Send failed at frame {frame_seq}")
                    break
                frame_seq += 1

            if not self._send_frame("L|1|N"):
                logger.warning("[FIELD_QUERY] Terminator frame send failed")

        # End transmission
        self._send(EOT)
        logger.info(f"[FIELD_QUERY] Response complete for {self.addr}")

    def send_results_query_response(self):
        """Send a template-backed P/O/R response for H+Q results-query flows."""
        logger.info(f"[RESULTS_QUERY] Sending response to {self.addr}")

        self._send(ENQ)
        try:
            response = self._receive_byte()
            if response != ACK:
                logger.warning(
                    f"[RESULTS_QUERY] Did not receive ACK, got: {response.hex() if response else 'none'}"
                )
                return
        except socket.timeout:
            logger.warning("[RESULTS_QUERY] Timeout waiting for ACK")
            return

        try:
            if self.astm_template:
                message = ASTMHandler().generate(self.astm_template, use_seed=True)
                records = [r for r in message.strip().split('\n') if r.strip()]
            else:
                records = [
                    "H|\\^&|||MockAnalyzer^ASTM-Mock^1.0|||||||LIS2-A2",
                    "P|1|PAT-RESULTS||DOE^JANE",
                    "O|1|ACC-RESULTS",
                    "R|1|^^^GLUCOSE|102.5|mg/dL",
                    "L|1|N",
                ]

            for i, record in enumerate(records):
                if not self._send_frame(record.strip()):
                    logger.warning(
                        f"[RESULTS_QUERY] Send failed at record {i + 1}/{len(records)}"
                    )
                    break
            logger.info(f"[RESULTS_QUERY] Sent {len(records)} records to {self.addr}")
        finally:
            self._send(EOT)
            logger.info(f"[RESULTS_QUERY] Response complete for {self.addr}")

    def send_order_response(self, orders: List[Dict[str, str]]):
        """After receiving an inbound LIS order, push matching result records
        back via a FRESH TCP connection to the bridge's ASTM listener. The
        originating sample_id is echoed verbatim in the response O-record
        (ASTM field 3) — that is the protocol-native correlation OpenELIS's
        inbound result import keys on.

        Same-connection push doesn't work end-to-end: the bridge's outbound
        forwarder closes the TCP socket after sending EOT, so any response
        sent on `self.conn` is dropped. Mirrors the HL7 path which already
        opens a fresh MLLP connection back to bridge:2575 (see
        _push_order_result in protocols/mllp_listener.py).

        Destination defaults to the bridge's inbound ASTM listener:
          ORDER_RESULT_PUSH_HOST=openelis-analyzer-bridge
          ORDER_RESULT_PUSH_ASTM_PORT=12001
        Empty host disables the push (useful for standalone dev runs).

        Result values come from the loaded ASTM template's
        `fields[].seedValue` (NUMERIC) or `seedQualitative` (other). A test code
        not in this analyzer's profile gets an error-flagged result record (ASTM
        result status X = cannot obtain result) rather than being silently
        omitted or failing the whole response — so the mismatch stays visible.
        """
        if not self.astm_template:
            logger.warning("[ORDER_IN] No template loaded; cannot generate result records")
            return

        host = os.environ.get("ORDER_RESULT_PUSH_HOST", "openelis-analyzer-bridge")
        port_raw = os.environ.get("ORDER_RESULT_PUSH_ASTM_PORT", "12001")
        if not host:
            logger.info("[ORDER_IN] ORDER_RESULT_PUSH_HOST empty; ASTM result push disabled")
            return
        try:
            port = int(port_raw)
        except (TypeError, ValueError):
            logger.warning(
                "[ORDER_IN] ORDER_RESULT_PUSH_ASTM_PORT=%r invalid; skipping push", port_raw
            )
            return

        template_fields = {f.get('code'): f for f in self.astm_template.get('fields', [])}
        test_patient = self.astm_template.get('testPatient', {})
        patient_id = test_patient.get('id', 'PAT-ORDER')
        patient_name = test_patient.get('name', 'DOE^JOHN')

        # Group orders by sample so a multi-test order shares one P/O block.
        # dict preserves insertion order in Python 3.7+.
        samples: Dict[str, List[str]] = {}
        for order in orders:
            samples.setdefault(order['sample_id'], []).append(order['test_code'])

        # Stamp the analyzer's own identity in the H-record sender field so the
        # bridge can corroborate it against the connection source IP (mirrors
        # ASTMHandler.generate). A hardcoded sender would defeat content-based
        # identity on the order-response path.
        ident = self.astm_template.get("identification", {})
        astm_header = ident.get("astm_header")
        if not astm_header:
            anal = self.astm_template.get("analyzer", {})
            astm_header = (
                f"{anal.get('manufacturer', '')}^{anal.get('model', '')}^{anal.get('name', '')}".strip("^")
                or anal.get("name", "MockAnalyzer")
            )
        records: List[str] = [
            f"H|\\^&|||{astm_header}|||||||LIS2-A2",
        ]
        patient_seq = 1
        order_seq = 1
        result_seq = 1
        for sample_id, test_codes in samples.items():
            records.append(f"P|{patient_seq}|{patient_id}||{patient_name}")
            records.append(f"O|{order_seq}|{sample_id}|||^^^|R")
            patient_seq += 1
            order_seq += 1
            for test_code in test_codes:
                field = template_fields.get(test_code)
                if not field:
                    # Ordered a test this analyzer can't run. A faithful analyzer
                    # reports that (result status X = cannot obtain result) rather
                    # than silently omitting it, so the mismatch is visible.
                    logger.warning(
                        f"[ORDER_IN] Ordered test {test_code} not in analyzer profile; "
                        f"emitting error result (status X)"
                    )
                    records.append(f"R|{result_seq}|^^^{test_code}|TEST NOT PERFORMED|||||X")
                    result_seq += 1
                    continue
                if field.get('type') == 'NUMERIC':
                    value = field.get('seedValue', '')
                    unit = field.get('unit', '')
                else:
                    value = field.get('seedQualitative', '')
                    unit = ''
                records.append(f"R|{result_seq}|^^^{test_code}|{value}|{unit}||||F")
                result_seq += 1
        records.append("L|1|N")

        # push_astm_tcp opens a new TCP connection, performs ENQ/ACK/frames/EOT,
        # and returns True on success. Send each record as a single line; the
        # session helper handles framing.
        from push import push_astm_tcp
        message = "\n".join(records)
        # Source the push from the interface the order arrived on (this analyzer's
        # IP = the inbound connection's LOCAL address). The mock is attached to one
        # network per analyzer; the bridge identifies the source analyzer by the
        # push's source IP, so an unbound push from an arbitrary interface gets
        # mis-attributed. NOTE: self.conn.getsockname() (local), not self.addr (the
        # bridge's remote address).
        try:
            source_ip = self.conn.getsockname()[0]
        except OSError:
            source_ip = None
        logger.info(
            f"[ORDER_IN] Pushing {len(records)} ASTM result records for {len(orders)} order(s) "
            f"to {host}:{port} (source={source_ip})"
        )
        try:
            ok, push_err = push_astm_tcp(host, port, message, timeout=10, source_ip=source_ip)
            if ok:
                logger.info(
                    f"[ORDER_IN] Pushed ASTM result message to {host}:{port}"
                )
            else:
                logger.warning(
                    f"[ORDER_IN] push_astm_tcp returned false for {host}:{port}: {push_err}"
                )
        except Exception as e:
            logger.error(
                f"[ORDER_IN] Exception pushing ASTM result to {host}:{port}: {e}",
                exc_info=True,
            )

    def _send_frames_from_template(self):
        """Send template data as ASTM frames (ENQ/ACK already established).

        Used by proactive ENQ flow where the handshake is handled by the caller.
        """
        if self.astm_template:
            message = ASTMHandler().generate(self.astm_template, use_seed=True)
            records = [r for r in message.strip().split('\n') if r.strip()]
            for i, record in enumerate(records):
                if not self._send_frame(record.strip()):
                    logger.warning(f"[PROACTIVE_ENQ] Send failed at record {i+1}/{len(records)}")
                    break
            logger.info(f"[PROACTIVE_ENQ] Sent {len(records)} records to {self.addr}")
        self._send(EOT)

    def _send_frame(self, content: str):
        """Send an ASTM frame with proper framing."""
        # CLSI LIS01-A2 §6.3.2.1: Frame numbers 0-7, begin at 1, wrap 7→0.
        # Sequence: 1,2,3,4,5,6,7,0,1,2,...  Formula: (index + 1) % 8
        self.frame_number = (self.frame_number + 1) % 8
        
        # Build frame: <STX><FN><content><ETX><checksum><CR><LF>
        frame_num = str(self.frame_number).encode()
        content_bytes = content.encode('utf-8')
        
        # Calculate checksum (sum of bytes from frame num to ETX, mod 256)
        checksum_data = frame_num + content_bytes + ETX
        checksum = sum(checksum_data) % 256
        checksum_str = f'{checksum:02X}'.encode()
        
        frame = STX + frame_num + content_bytes + ETX + checksum_str + CR + LF
        self.conn.send(frame)
        
        # Wait for ACK with proper timeout per CLSI LIS1-A
        self.conn.settimeout(FRAME_ACK_TIMEOUT)
        try:
            response = self.conn.recv(1)
            if response == EOT:
                # Receiver interrupt request per CLSI LIS1-A 8.3.5
                logger.info("Receiver interrupt requested (EOT received)")
                return False  # Signal to stop sending
            elif response != ACK:
                logger.warning(f"Frame not ACKed: {response.hex() if response else 'none'}")
                # Per CLSI LIS1-A: Should retransmit on NAK, abort after 6 failures
                return False
        except socket.timeout:
            logger.warning("Timeout waiting for frame ACK (15s limit per CLSI LIS1-A)")
            return False
        
        return True
            
    def _cleanup(self):
        """Clean up connection resources."""
        try:
            self.conn.close()
        except:
            pass
        logger.info(f"Client disconnected: {self.addr}")


class ASTMMockServer:
    """ASTM LIS2-A2 Mock Server for analyzer testing.

    Supports template-driven mode via ASTM_TEMPLATE env var (single port) or
    port-to-template mapping (multi-port). When a connection is accepted, the
    template is selected by the port (request-based); the handler loads the
    template and processes the message accordingly.
    """

    def __init__(self, port: int = DEFAULT_PORT,
                 analyzer_type: str = DEFAULT_ANALYZER_TYPE,
                 response_delay_ms: int = DEFAULT_RESPONSE_DELAY_MS,
                 port_to_template: Optional[Dict[int, str]] = None):
        self.port = port
        self.analyzer_type = analyzer_type
        self.response_delay_ms = response_delay_ms
        self.fields_config = self._load_fields_config()
        if port_to_template is None:
            port_to_template = _load_port_templates(port)
        self.port_to_template = port_to_template
        if port_to_template:
            self.ports = sorted(port_to_template.keys())
            self.astm_template = None
        else:
            self.ports = [port]
            self.astm_template = self._load_astm_template()
        self.running = False
        self.server_sockets: List[socket.socket] = []
        self.client_threads: List[threading.Thread] = []

    def _load_astm_template(self) -> Optional[Dict]:
        """Load ASTM template from ASTM_TEMPLATE env var if set."""
        template_name = os.environ.get('ASTM_TEMPLATE')
        if not template_name:
            return None
        template = _load_template(template_name)
        if template:
            proto = template.get('protocol', {}).get('type', '')
            name = template.get('analyzer', {}).get('name', template_name)
            if proto != 'ASTM':
                logger.warning(f"ASTM_TEMPLATE={template_name} is not ASTM protocol ({proto}), ignoring")
                return None
            logger.info(f"Loaded ASTM template: {name} ({template_name})")
        else:
            logger.warning(f"ASTM_TEMPLATE={template_name} not found in templates/")
        return template
        
    def _load_fields_config(self) -> Dict:
        """Load analyzer field configuration from JSON file."""
        config_path = os.path.join(os.path.dirname(__file__), 'fields.json')
        
        if os.path.exists(config_path):
            try:
                with open(config_path, 'r') as f:
                    return json.load(f)
            except Exception as e:
                logger.error(f"Error loading fields.json: {e}")
                
        # Return default configuration if file not found
        return self._get_default_fields()
        
    def _get_default_fields(self) -> Dict:
        """Return default field configuration."""
        return {
            "HEMATOLOGY": [
                {"name": "WBC", "astmRef": "R|1|^^^WBC", "type": "NUMERIC", "unit": "10^3/μL"},
                {"name": "RBC", "astmRef": "R|1|^^^RBC", "type": "NUMERIC", "unit": "10^6/μL"},
                {"name": "HGB", "astmRef": "R|1|^^^HGB", "type": "NUMERIC", "unit": "g/dL"},
                {"name": "HCT", "astmRef": "R|1|^^^HCT", "type": "NUMERIC", "unit": "%"},
                {"name": "PLT", "astmRef": "R|1|^^^PLT", "type": "NUMERIC", "unit": "10^3/μL"}
            ],
            "CHEMISTRY": [
                {"name": "Glucose", "astmRef": "R|1|^^^GLUCOSE", "type": "NUMERIC", "unit": "mg/dL"},
                {"name": "Creatinine", "astmRef": "R|1|^^^CREATININE", "type": "NUMERIC", "unit": "mg/dL"}
            ]
        }
        
    def start(self):
        """Start the mock server (single or multi-port)."""
        self.running = True
        try:
            if self.port_to_template:
                self._start_multi_port()
            else:
                self._start_single_port()
        except KeyboardInterrupt:
            logger.info("Server shutdown requested")
        except Exception as e:
            logger.error(f"Server error: {e}")
        finally:
            self.stop()

    def _start_single_port(self):
        """Single-port mode: one socket, one template (legacy)."""
        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
        sock.bind(('0.0.0.0', self.port))
        sock.listen(MAX_CONNECTIONS)
        self.server_sockets.append(sock)
        logger.info("ASTM Mock Server started on port %s", self.port)
        logger.info("Analyzer type: %s", self.analyzer_type)
        logger.info("Response delay: %sms", self.response_delay_ms)
        while self.running:
            try:
                sock.settimeout(1.0)
                conn, addr = sock.accept()
                handler = ASTMProtocolHandler(
                    conn, addr, self.fields_config, self.response_delay_ms,
                    astm_template=self.astm_template
                )
                thread = threading.Thread(target=handler.handle, daemon=True)
                thread.start()
                self.client_threads.append(thread)
            except socket.timeout:
                continue

    def _resolve_protocol_for_port(self, port: int) -> str:
        """Determine protocol type for a port by checking its template.

        Returns 'HL7' or 'ASTM' (default). Both are equal citizens —
        the template's protocol.type field determines the handler.
        """
        template_name = self.port_to_template.get(port)
        if template_name:
            template = _load_template(template_name)
            if template:
                proto = template.get("protocol", {}).get("type", "").upper()
                if proto == "HL7":
                    return "HL7"
        return "ASTM"

    def _start_multi_port(self):
        """Multi-port mode: one socket per port, protocol-aware handler dispatch.

        Each port maps to a template. The template's protocol.type determines
        which handler serves connections on that port:
          - ASTM → ASTMProtocolHandler (ENQ/ACK framing)
          - HL7  → MLLPProtocolHandler (VT/FS framing + HL7 ACK)
        """
        # Pre-resolve protocol per port for logging and dispatch
        port_protocols = {}
        for port in self.ports:
            proto = self._resolve_protocol_for_port(port)
            port_protocols[port] = proto
            sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
            sock.bind(('0.0.0.0', port))
            sock.listen(MAX_CONNECTIONS)
            sock.setblocking(False)
            self.server_sockets.append(sock)

        astm_ports = [p for p, proto in port_protocols.items() if proto == "ASTM"]
        hl7_ports = [p for p, proto in port_protocols.items() if proto == "HL7"]
        logger.info("Mock Server started on %d ports (ASTM: %s, HL7/MLLP: %s)",
                     len(self.ports), astm_ports or "none", hl7_ports or "none")
        logger.info("Response delay: %sms", self.response_delay_ms)

        while self.running:
            try:
                readable, _, _ = select.select(self.server_sockets, [], [], 1.0)
                for sock in readable:
                    conn, addr = sock.accept()
                    local_port = sock.getsockname()[1]
                    proto = port_protocols.get(local_port, "ASTM")

                    if proto == "HL7":
                        template_name = self.port_to_template.get(local_port)
                        template = _load_template(template_name) if template_name else None
                        handler = MLLPProtocolHandler(
                            conn, addr,
                            template=template,
                            template_name=template_name,
                            response_delay_ms=self.response_delay_ms,
                        )
                    else:
                        handler = ASTMProtocolHandler(
                            conn, addr, self.fields_config, self.response_delay_ms,
                            astm_template=None,
                            local_port=local_port,
                            port_to_template=self.port_to_template
                        )

                    thread = threading.Thread(target=handler.handle, daemon=True)
                    thread.start()
                    self.client_threads.append(thread)
            except (select.error, OSError) as e:
                if self.running:
                    logger.debug("select: %s", e)
                continue

    def stop(self):
        """Stop the mock server."""
        self.running = False
        for sock in self.server_sockets:
            try:
                sock.close()
            except Exception:
                pass
        self.server_sockets.clear()
        logger.info("ASTM Mock Server stopped")


def _load_template(analyzer: str) -> Optional[Dict]:
    """Load an analyzer's mock template.

    The on-disk templates/<analyzer>.json carries transport/framing mechanics +
    mock test fixtures and references its canonical profile via a `profile` key.
    The assay menu (`fields`) is then derived from that profile — single source of
    truth. Templates without a `profile` key fall back to their own `fields`
    (legacy, pending migration)."""
    base = os.path.dirname(os.path.abspath(__file__))
    path = os.path.join(base, "templates", f"{analyzer}.json")
    if not os.path.exists(path):
        return None
    try:
        with open(path, "r") as f:
            template = json.load(f)
    except Exception as e:
        logger.warning("Failed to load template %s: %s", path, e)
        return None

    try:
        from profile_adapter import load_profile_backed_template

        merged = load_profile_backed_template(analyzer, template)
        if merged is not None:
            return merged
    except Exception as e:
        logger.warning("Failed to derive profile-backed template for %s: %s", analyzer, e)

    return template


def _load_port_templates(default_port: int) -> Dict[int, str]:
    """Load port-to-template mapping from config or env.

    Returns a dict mapping port (int) to template name (str). Used for
    protocol-aware dispatch: each port maps to a template, and the template's
    protocol.type (ASTM or HL7) determines the connection handler.

    Env vars (checked in order):
      PORT_TEMPLATES          — protocol-agnostic (preferred)
      ASTM_PORT_TEMPLATES     — backward-compatible alias

    If no env var and ASTM_TEMPLATE is set, returns {default_port: ASTM_TEMPLATE}.
    """
    base = os.path.dirname(os.path.abspath(__file__))
    port_to_template: Dict[int, str] = {}

    # PORT_TEMPLATES is the preferred env var; ASTM_PORT_TEMPLATES is kept for compat
    env_json = os.environ.get("PORT_TEMPLATES") or os.environ.get("ASTM_PORT_TEMPLATES")
    if env_json is not None:
        try:
            raw = json.loads(env_json)
            if isinstance(raw, dict):
                for k, v in raw.items():
                    if v and isinstance(v, str):
                        try:
                            port_to_template[int(k)] = v
                        except (ValueError, TypeError):
                            logger.warning("Skipping non-numeric port key %r", k)
        except json.JSONDecodeError as e:
            logger.warning("Invalid ASTM_PORT_TEMPLATES JSON: %s", e)
    else:
        config_path = os.path.join(base, "config", "port_templates.json")
        if os.path.exists(config_path):
            try:
                with open(config_path, "r") as f:
                    raw = json.load(f)
                for k, v in raw.items():
                    if v and isinstance(v, str):
                        try:
                            port_to_template[int(k)] = v
                        except (ValueError, TypeError):
                            logger.warning("Skipping non-numeric port key %r", k)
            except Exception as e:
                logger.warning("Failed to load port_templates.json: %s", e)

    if not port_to_template and os.environ.get("ASTM_TEMPLATE"):
        port_to_template[default_port] = os.environ.get("ASTM_TEMPLATE")

    return port_to_template



def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description='ASTM LIS2-A2 Mock Server for OpenELIS Analyzer Testing'
    )
    parser.add_argument(
        '--port', '-p',
        type=int,
        default=int(os.environ.get('ASTM_PORT', DEFAULT_PORT)),
        help=f'Server port (default: {DEFAULT_PORT})'
    )
    parser.add_argument(
        '--analyzer-type', '-t',
        type=str,
        default=os.environ.get('ANALYZER_TYPE', DEFAULT_ANALYZER_TYPE),
        help=f'Analyzer type (default: {DEFAULT_ANALYZER_TYPE})'
    )
    parser.add_argument(
        '--response-delay', '-d',
        type=int,
        default=int(os.environ.get('RESPONSE_DELAY_MS', DEFAULT_RESPONSE_DELAY_MS)),
        help=f'Response delay in ms (default: {DEFAULT_RESPONSE_DELAY_MS})'
    )
    parser.add_argument(
        '--verbose', '-v',
        action='store_true',
        help='Enable verbose logging'
    )
    parser.add_argument(
        '--push', '-P',
        type=str,
        metavar='URL',
        help='Push mode: Send ASTM message to OpenELIS at URL (e.g., https://localhost:8443)'
    )
    parser.add_argument(
        '--template',
        type=str,
        metavar='NAME',
        default=os.environ.get('ASTM_TEMPLATE'),
        help='Template name to use for push mode (e.g. horiba_pentra60). Uses fields.json if not set.'
    )
    parser.add_argument(
        '--qc',
        action='store_true',
        help='QC push mode: generate ASTM QC message (H+O+R+Q+L) from template qc_controls. Requires --template.'
    )
    parser.add_argument(
        '--qc-deviation',
        type=float,
        default=None,
        metavar='SD',
        help='Shift QC results by exactly N standard deviations from target. '
             'Omit for realistic random scatter. '
             'Examples: 0=exact target, 2.5=warning (1₂ₛ), 3.5=rejection (1₃ₛ), -3.5=below target'
    )
    parser.add_argument(
        '--source-ip',
        default=None,
        metavar='IP',
        help='Local IP to bind the outgoing TCP socket to. The mock has '
             'multiple Docker network interfaces (one per registered '
             'analyzer); the bridge identifies analyzers by source IP, so '
             'multi-analyzer setups must specify this to route correctly. '
             'Example: --source-ip 10.42.20.10 for the genexpert network.'
    )
    parser.add_argument(
        '--dry-run',
        action='store_true',
        help='Print the generated ASTM message without sending it. Works with --push, --qc, --template.'
    )
    parser.add_argument(
        '--push-count', '-c',
        type=int,
        default=1,
        help='Number of messages to push (default: 1)'
    )
    parser.add_argument(
        '--push-interval', '-i',
        type=int,
        default=1,
        help='Interval between pushes in seconds (default: 1)'
    )
    parser.add_argument(
        '--push-continuous', '-C',
        action='store_true',
        help='Continuous push mode: Push messages indefinitely at specified interval (simulates real analyzer behavior)'
    )
    parser.add_argument(
        '--api-port', '-a',
        type=int,
        metavar='PORT',
        help='Start HTTP API server on specified port for triggering pushes (e.g., 8080)'
    )
    parser.add_argument(
        '--simulate-api-port',
        type=int,
        metavar='PORT',
        help='M4: Start simulate API (GET/POST /simulate/hl7/{analyzer}) for CI/CD (e.g., 8081)'
    )
    parser.add_argument(
        '--serial-port',
        type=str,
        metavar='PATH',
        help='M4: Serial simulation mode: send ASTM over port (e.g. /dev/pts/X via socat)'
    )
    parser.add_argument(
        '--serial-analyzer',
        type=str,
        default='horiba_pentra60',
        help='M4: Template name for --serial-port (default: horiba_pentra60)'
    )
    parser.add_argument(
        '--generate-files',
        type=str,
        metavar='DIR',
        help='M4: File generation mode: write CSV to DIR (use with --generate-files-analyzer)'
    )
    parser.add_argument(
        '--generate-files-analyzer',
        type=str,
        default='quantstudio7',
        help='M4: Template for --generate-files (default: quantstudio7)'
    )
    parser.add_argument(
        '--hl7',
        action='store_true',
        help='HL7 mode: use HL7 template and push ORU^R01 to destination (use with --push)'
    )
    parser.add_argument(
        '--hl7-template',
        type=str,
        metavar='NAME',
        default=os.environ.get('HL7_TEMPLATE', 'abbott_architect_hl7'),
        help='HL7 template name (default: abbott_architect_hl7 or HL7_TEMPLATE env)'
    )
    args = parser.parse_args()
    
    if args.verbose:
        logging.getLogger().setLevel(logging.DEBUG)

    # M4: File generation mode
    if getattr(args, 'generate_files', None):
        out_dir = args.generate_files
        analyzer = getattr(args, 'generate_files_analyzer', None) or 'quantstudio7'
        template = _load_template(analyzer)
        if not template:
            logger.error("Template not found: %s", analyzer)
            return 1
        fcfg = template.get("file_config") or {}
        pat = (template.get("identification") or {}).get("file_pattern", "sim_%s.csv")
        fname = (pat % uuid.uuid4().hex[:8]) if "%" in pat else f"sim_{analyzer}_{uuid.uuid4().hex[:8]}.csv"
        path = os.path.join(out_dir, fname)
        ok = FileHandler().write_to_file(template, path, sample_count=1)
        if ok:
            print("Wrote %s" % ok)
            return 0
        return 1

    # M4: Serial simulation mode
    if getattr(args, 'serial_port', None):
        port_path = args.serial_port
        analyzer = getattr(args, 'serial_analyzer', None) or 'horiba_pentra60'
        template = _load_template(analyzer)
        if not template:
            logger.error("Template not found: %s", analyzer)
            return 1
        cfg = template.get("serial_config") or {}
        baud = int(cfg.get("baud_rate", 9600))
        msg = SerialHandler().generate(template)
        print("=" * 60)
        print("  Multi-Protocol Simulator - Serial Mode")
        print("=" * 60)
        print("  Port: %s  Analyzer: %s  Baud: %s" % (port_path, analyzer, baud))
        print("=" * 60)
        ok = send_astm_over_serial(port_path, msg, baud=baud)
        return 0 if ok else 1

    # HL7 push mode: Send ORU^R01 to OpenELIS (template-driven, e.g. Abbott)
    if args.hl7 and args.push:
        if not HAS_HL7_SIM:
            logger.error("HL7 simulation not available (template_loader or hl7_handler missing)")
            return 1
        try:
            loader = TemplateLoader()
            template = loader.load_template(args.hl7_template)
        except FileNotFoundError as e:
            logger.error("HL7 template not found: %s", e)
            return 1
        except Exception as e:
            logger.error("Failed to load HL7 template: %s", e)
            return 1
        if template.get('protocol', {}).get('type') != 'HL7':
            logger.error("Template %s is not an HL7 template", args.hl7_template)
            return 1
        print("=" * 60)
        print("  ASTM Mock Server - HL7 Push Mode")
        print("=" * 60)
        print(f"  OpenELIS URL: {args.push}")
        print(f"  HL7 Template: {args.hl7_template}")
        print(f"  Message Count: {args.push_count}")
        print(f"  Interval: {args.push_interval}s")
        print("=" * 60)
        print()
        success_count = 0
        total_sent = 0
        try:
            if args.push_continuous:
                while True:
                    total_sent += 1
                    msg = generate_oru_r01(template, deterministic=True)
                    if push_hl7_http(args.push, msg):
                        success_count += 1
                    time.sleep(args.push_interval)
            else:
                for i in range(args.push_count):
                    msg = generate_oru_r01(template, deterministic=True)
                    if push_hl7_http(args.push, msg):
                        success_count += 1
                    total_sent += 1
                    if i < args.push_count - 1:
                        time.sleep(args.push_interval)
        except KeyboardInterrupt:
            # Allow user-initiated interruption and proceed to summary output
            pass
        print()
        print("=" * 60)
        print(f"  HL7 Push Complete: {success_count}/{total_sent} successful")
        print("=" * 60)
        return 0 if (not args.push_continuous and success_count == args.push_count) or (args.push_continuous and total_sent > 0) else 1

    # Push mode: Send ASTM messages to OpenELIS
    if args.push:
        print("=" * 60)
        print("  ASTM Mock Server - Push Mode")
        print("=" * 60)
        mode_label = "QC" if args.qc else "Patient"
        print(f"  OpenELIS URL: {args.push}")
        print(f"  Template:     {args.template or '(fields.json / --analyzer-type)'}")
        print(f"  Mode:         {mode_label}")
        print(f"  Message Count: {args.push_count}")
        print(f"  Interval: {args.push_interval}s")
        print("=" * 60)
        print()

        if args.qc and not args.template:
            logger.error("--qc requires --template (fields.json has no qc_controls)")
            return 1

        # Resolve message generator: template-driven or legacy fields.json
        push_template = None
        if args.template:
            template_path = os.path.join(os.path.dirname(__file__), 'templates', f'{args.template}.json')
            if not os.path.exists(template_path):
                logger.error(f"Template not found: {template_path}")
                return 1
            with open(template_path, 'r') as f:
                push_template = json.load(f)
            if push_template.get('protocol', {}).get('type') != 'ASTM':
                logger.error(f"Template '{args.template}' is not an ASTM template")
                return 1
            logger.info(f"Using template: {push_template['analyzer']['name']} [{mode_label}]")

        def generate_push_message() -> Optional[str]:
            if push_template:
                handler = ASTMHandler()
                if args.qc:
                    return handler.generate_qc(push_template, deviation=args.qc_deviation)
                return handler.generate(push_template)
            fields_file = os.path.join(os.path.dirname(__file__), 'fields.json')
            try:
                with open(fields_file, 'r') as f:
                    fields_config = json.load(f)
            except Exception as e:
                logger.error(f"Error loading fields.json: {e}")
                return None
            return generate_astm_message(analyzer_type=args.analyzer_type, fields_config=fields_config)

        # Dry run: print message and exit
        if args.dry_run:
            message = generate_push_message()
            if message:
                print(message)
            else:
                logger.error("Failed to generate message")
            return

        # Push messages
        success_count = 0
        total_pushed = 0

        if args.push_continuous:
            # Continuous mode: Push indefinitely (simulates real analyzer behavior)
            logger.info("Starting continuous push mode (press Ctrl+C to stop)")
            try:
                while True:
                    total_pushed += 1
                    logger.info(f"Generating and pushing message #{total_pushed}")
                    message = generate_push_message()
                    if not message:
                        logger.error("Failed to generate message")
                        time.sleep(args.push_interval)
                        continue
                    push_ok, push_err = push_astm_to_destination(args.push, message, source_ip=args.source_ip)
                    if push_ok:
                        success_count += 1
                    else:
                        logger.warning(f"Push #{total_pushed} failed: {push_err}")
                    time.sleep(args.push_interval)
            except KeyboardInterrupt:
                logger.info("Continuous push mode stopped by user")
        else:
            # Batch mode: Push specified number of messages
            for i in range(args.push_count):
                total_pushed += 1
                logger.info(f"Generating and pushing message {i+1}/{args.push_count}")
                message = generate_push_message()
                if not message:
                    logger.error("Failed to generate message")
                    continue
                push_ok, push_err = push_astm_to_destination(args.push, message, source_ip=args.source_ip)
                if push_ok:
                    success_count += 1
                else:
                    logger.warning(f"Push {i+1} failed: {push_err}")
                if i < args.push_count - 1:
                    time.sleep(args.push_interval)
        
        print()
        print("=" * 60)
        if args.push_continuous:
            print(f"  Push Complete: {success_count}/{total_pushed} successful")
        else:
            print(f"  Push Complete: {success_count}/{args.push_count} successful")
        print("=" * 60)
        return 0 if success_count == total_pushed else 1
    
    # Start unified API server in background thread if requested
    api_port = getattr(args, 'simulate_api_port', None) or getattr(args, 'api_port', None)
    if api_port:
        api_thread = threading.Thread(
            target=start_api_server,
            args=(api_port,),
            daemon=True,
        )
        api_thread.start()
        logger.info("API server started on port %s (background)", api_port)

    # Server mode: Listen for connections
    print("=" * 60)
    print("  ASTM LIS2-A2 Mock Server for OpenELIS")
    port_to_template = _load_port_templates(args.port)
    print("=" * 60)
    if port_to_template:
        print(f"  Ports: {sorted(port_to_template.keys())} (port-to-template)")
    else:
        print(f"  Port: {args.port}")
    print(f"  Analyzer Type: {args.analyzer_type}")
    print(f"  Response Delay: {args.response_delay}ms")
    if api_port:
        print(f"  API Server: {api_port}")
    print("=" * 60)
    print("  Press Ctrl+C to stop")
    print("=" * 60)
    print()

    server = ASTMMockServer(
        port=args.port,
        analyzer_type=args.analyzer_type,
        response_delay_ms=args.response_delay,
        port_to_template=port_to_template if port_to_template else None
    )
    server.start()


if __name__ == '__main__':
    main()