reader.go

// Copyright 2026 Joshua Jones <joshua.jones.software@gmail.com>
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//    http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package hl7

import (
	"bufio"
	"bytes"
	"io"
)

// MLLP framing bytes per the HL7 transport specification.
const (
	mllpStartBlock byte = 0x0B // VT - start of MLLP message
	mllpEndBlock   byte = 0x1C // FS - end of MLLP message
	mllpCR         byte = 0x0D // CR - follows end block
)

// ReaderMode controls how the Reader identifies message boundaries.
type ReaderMode int

const (
	// ModeAuto detects MLLP framing by looking for the 0x0B start byte.
	// Falls back to raw mode if not found.
	ModeAuto ReaderMode = iota

	// ModeMLLP expects MLLP framing (0x0B + data + 0x1C + 0x0D).
	ModeMLLP

	// ModeRaw reads messages by looking for MSH segment boundaries.
	// Each message starts with "MSH" and ends before the next "MSH" or EOF.
	ModeRaw
)

const defaultBufSize = 32 * 1024 // 32 KB

// Reader reads HL7 messages from an io.Reader.
// It supports MLLP-framed and raw message streams.
type Reader struct {
	r            *bufio.Reader
	mode         ReaderMode
	buf          bytes.Buffer // Reusable buffer to reduce allocations.
	maxFrameSize int
}

// ReaderOption configures a Reader.
type ReaderOption func(*Reader)

// WithMode sets the reader mode.
func WithMode(m ReaderMode) ReaderOption {
	return func(r *Reader) {
		r.mode = m
	}
}

// WithMaxFrameSize sets the maximum allowed MLLP frame size in bytes.
// If a frame exceeds this size during reading, ReadMessage returns
// ErrFrameTooLarge. A value of 0 (the default) imposes no limit.
func WithMaxFrameSize(n int) ReaderOption {
	return func(r *Reader) { r.maxFrameSize = n }
}

// WithBufferSize sets the underlying bufio.Reader size.
func WithBufferSize(n int) ReaderOption {
	return func(r *Reader) {
		r.r = bufio.NewReaderSize(r.r, n)
	}
}

// NewReader creates a Reader that reads HL7 messages from r.
func NewReader(r io.Reader, opts ...ReaderOption) *Reader {
	rd := &Reader{
		r:    bufio.NewReaderSize(r, defaultBufSize),
		mode: ModeAuto,
	}
	for _, opt := range opts {
		opt(rd)
	}
	return rd
}

// ReadMessage reads the next complete HL7 message from the stream,
// parses it, and returns the structured Message.
//
// Returns io.EOF when no more messages are available.
func (rd *Reader) ReadMessage() (*Message, error) {
	raw, err := rd.ReadRawMessage()
	if err != nil {
		return nil, err
	}
	return ParseMessage(raw)
}

// ReadRawMessage reads the next raw message bytes from the stream
// without parsing. Useful for forwarding or custom handling.
//
// Returns io.EOF when no more messages are available.
func (rd *Reader) ReadRawMessage() ([]byte, error) {
	mode := rd.mode

	if mode == ModeAuto {
		detected, err := rd.detectMode()
		if err != nil {
			return nil, err
		}
		mode = detected
	}

	switch mode {
	case ModeMLLP:
		return rd.readMLLP()
	default:
		return rd.readRaw()
	}
}

// EachMessage calls fn for each message read from the stream.
// Iteration stops on the first error returned by fn, or when the
// stream is exhausted (io.EOF). Returns nil on normal EOF.
func (rd *Reader) EachMessage(fn func(*Message) error) error {
	for {
		msg, err := rd.ReadMessage()
		if err != nil {
			if err == io.EOF {
				return nil
			}
			return err
		}
		if err := fn(msg); err != nil {
			return err
		}
	}
}

// detectMode peeks at the next non-whitespace byte to determine framing.
func (rd *Reader) detectMode() (ReaderMode, error) {
	for {
		b, err := rd.r.Peek(1)
		if err != nil {
			return ModeAuto, err
		}
		switch b[0] {
		case mllpStartBlock:
			return ModeMLLP, nil
		case ' ', '\t', '\n', '\r':
			// Skip leading whitespace.
			rd.r.ReadByte()
			continue
		default:
			return ModeRaw, nil
		}
	}
}

// readMLLP reads a single MLLP-framed message.
// Format: 0x0B + message_data + 0x1C + 0x0D
func (rd *Reader) readMLLP() ([]byte, error) {
	// Read and verify start block.
	b, err := rd.r.ReadByte()
	if err != nil {
		return nil, err
	}
	if b != mllpStartBlock {
		// Skip whitespace before start block.
		for b == ' ' || b == '\t' || b == '\n' || b == '\r' {
			b, err = rd.r.ReadByte()
			if err != nil {
				return nil, err
			}
		}
		if b != mllpStartBlock {
			return nil, ErrMLLPMissingStart
		}
	}

	// Read until end block (0x1C).
	rd.buf.Reset()
	for {
		b, err := rd.r.ReadByte()
		if err != nil {
			if err == io.EOF {
				return nil, ErrMLLPMissingEnd
			}
			return nil, err
		}
		if b == mllpEndBlock {
			break
		}
		rd.buf.WriteByte(b)
		if rd.maxFrameSize > 0 && rd.buf.Len() > rd.maxFrameSize {
			return nil, ErrFrameTooLarge
		}
	}

	// Read and verify trailing CR.
	b, err = rd.r.ReadByte()
	if err != nil && err != io.EOF {
		return nil, err
	}
	// Some implementations omit the trailing CR; tolerate this.

	// Return a copy of the buffered data.
	result := make([]byte, rd.buf.Len())
	copy(result, rd.buf.Bytes())
	return result, nil
}

// readRaw reads a message in raw mode by looking for MSH boundaries.
// Each message starts at an "MSH" marker and extends until the next
// "MSH" marker or EOF.
func (rd *Reader) readRaw() ([]byte, error) {
	rd.buf.Reset()

	// Skip any leading whitespace/blank lines.
	for {
		b, err := rd.r.ReadByte()
		if err != nil {
			return nil, err
		}
		if b != '\r' && b != '\n' && b != ' ' && b != '\t' {
			rd.buf.WriteByte(b)
			break
		}
	}

	// Read lines until we hit the start of a new message or EOF.
	for {
		line, err := rd.r.ReadBytes('\n')
		if len(line) > 0 {
			// Check if this line starts a new MSH segment.
			trimmed := bytes.TrimLeft(line, "\r\n")
			if len(trimmed) >= 3 && trimmed[0] == 'M' && trimmed[1] == 'S' && trimmed[2] == 'H' && rd.buf.Len() > 0 {
				// Push the line back — it belongs to the next message.
				// We can't unread the whole line with bufio, so we use
				// a trick: prepend the line bytes back.
				combined := make([]byte, len(line)+rd.r.Buffered())
				copy(combined, line)
				// Actually, we need to reconstruct the reader state.
				// The simplest approach: create a new reader with the
				// unread data prepended.
				remaining := make([]byte, rd.r.Buffered())
				n, _ := rd.r.Read(remaining)
				remaining = remaining[:n]
				rd.r = bufio.NewReaderSize(
					io.MultiReader(bytes.NewReader(line), bytes.NewReader(remaining), readerFromBufio(rd.r)),
					defaultBufSize,
				)
				break
			}
			rd.buf.Write(line)
		}
		if err != nil {
			if err == io.EOF {
				break
			}
			return nil, err
		}
	}

	if rd.buf.Len() == 0 {
		return nil, io.EOF
	}

	result := make([]byte, rd.buf.Len())
	copy(result, rd.buf.Bytes())

	// Trim trailing whitespace.
	result = bytes.TrimRight(result, "\r\n \t")
	if len(result) == 0 {
		return nil, io.EOF
	}

	return result, nil
}

// readerFromBufio wraps a bufio.Reader back into an io.Reader.
// This is needed when reconstructing the reader after pushing back data.
type bufioReader struct {
	r *bufio.Reader
}

func readerFromBufio(r *bufio.Reader) io.Reader {
	return &bufioReader{r: r}
}

func (br *bufioReader) Read(p []byte) (int, error) {
	return br.r.Read(p)
}