ack.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 (
	"strconv"
	"time"
)

// AckCode represents an HL7v2 acknowledgment code (MSA-1).
type AckCode string

const (
	AA AckCode = "AA" // Application Accept
	AE AckCode = "AE" // Application Error
	AR AckCode = "AR" // Application Reject
	CA AckCode = "CA" // Commit Accept
	CE AckCode = "CE" // Commit Error
	CR AckCode = "CR" // Commit Reject
)

// AckOption configures optional fields on an ACK message.
type AckOption func(*ackBuilder)

// WithText sets MSA-3 (text message) for error context.
func WithText(text string) AckOption {
	return func(b *ackBuilder) {
		b.text = text
	}
}

// WithTimestamp overrides the default time.Now() for MSH-7.
func WithTimestamp(t time.Time) AckOption {
	return func(b *ackBuilder) {
		b.timestamp = t
	}
}

// WithErrors adds ERR segments to the ACK message, one per Issue.
// Issues are typically obtained from Validate:
//
//	result := msg.Validate(schema)
//	ack, err := msg.Ack(hl7.AE, "ACK001", hl7.WithErrors(result.Issues))
//
// Each Issue maps to one ERR segment with error location (ERR-2),
// severity (ERR-4), application error code (ERR-5), and diagnostic
// information (ERR-7).
func WithErrors(issues []Issue) AckOption {
	return func(b *ackBuilder) {
		b.errors = issues
	}
}

type ackBuilder struct {
	text      string
	timestamp time.Time
	errors    []Issue
}

// Ack creates an ACK message in response to this message.
// The controlID is used as MSH-10 of the ACK. The caller is responsible
// for generating unique control IDs.
//
// The ACK copies delimiters and swaps sender/receiver fields from the
// original MSH segment. Field values are copied as raw bytes to preserve
// any escape sequences.
//
// Returns ErrNoMSHSegment if the message has no MSH segment.
func (m *Message) Ack(code AckCode, controlID string, opts ...AckOption) ([]byte, error) {
	if len(m.segments) == 0 || m.segments[0].Type() != "MSH" {
		return nil, ErrNoMSHSegment
	}

	ab := ackBuilder{timestamp: time.Now()}
	for _, opt := range opts {
		opt(&ab)
	}

	msh := &m.segments[0]
	d := m.delims
	f := d.Field
	ts := ab.timestamp.Format("20060102150405")

	// Pre-calculate buffer size to avoid growing.
	// MSH: "MSH" + separator + encoding chars + 10 delimited fields
	// MSA: "MSA" + code + control ID + optional text
	sendApp := msh.Field(5).Raw()
	sendFac := msh.Field(6).Raw()
	recvApp := msh.Field(3).Raw()
	recvFac := msh.Field(4).Raw()
	triggerEvent := msh.Field(9).Rep(0).Component(2).Raw()
	procID := msh.Field(11).Raw()
	versionID := msh.Field(12).Raw()
	origControlID := msh.Field(10).Raw()

	// Estimate size: MSH header + fields + MSA segment.
	size := 3 + 1 + 4 + // "MSH" + separator + encoding chars
		1 + len(sendApp) +
		1 + len(sendFac) +
		1 + len(recvApp) +
		1 + len(recvFac) +
		1 + len(ts) +
		1 + // empty field (MSH-8)
		1 + 3 + 1 + len(triggerEvent) + 1 + 3 + // ACK^trigger^ACK
		1 + len(controlID) +
		1 + len(procID) +
		1 + len(versionID) +
		1 + // segment terminator
		3 + 1 + len(code) + 1 + len(origControlID) + // MSA|code|controlID
		1 // segment terminator

	if ab.text != "" {
		size += 1 + len(ab.text)
	}

	// Pre-escape and size ERR segments.
	type errData struct {
		erl  []byte // pre-built ERL field
		sev  byte   // 'E' or 'W'
		code []byte // escaped code
		desc []byte // escaped description
	}
	var errs []errData
	if len(ab.errors) > 0 {
		errs = make([]errData, len(ab.errors))
		for i, issue := range ab.errors {
			errs[i].erl = appendERL(nil, issue.Location, d)
			errs[i].sev = errSeverityByte(issue.Severity)
			errs[i].code = Escape([]byte(issue.Code), d)
			errs[i].desc = Escape([]byte(issue.Description), d)

			// "ERR" + 7 field separators + fields + \r
			size += 3 + 7 +
				len(errs[i].erl) + // ERR-2
				1 + // ERR-4 severity
				len(errs[i].code) + // ERR-5
				len(errs[i].desc) + // ERR-7
				1 // segment terminator
		}
	}

	buf := make([]byte, 0, size)

	// MSH segment.
	buf = append(buf, 'M', 'S', 'H')
	buf = append(buf, f)
	buf = append(buf, d.Component, d.Repetition, d.Escape, d.SubComponent)
	buf = append(buf, f)
	buf = append(buf, sendApp...)
	buf = append(buf, f)
	buf = append(buf, sendFac...)
	buf = append(buf, f)
	buf = append(buf, recvApp...)
	buf = append(buf, f)
	buf = append(buf, recvFac...)
	buf = append(buf, f)
	buf = append(buf, ts...)
	buf = append(buf, f) // MSH-8 (security) — empty
	buf = append(buf, f)
	buf = append(buf, 'A', 'C', 'K')
	if len(triggerEvent) > 0 {
		buf = append(buf, d.Component)
		buf = append(buf, triggerEvent...)
		buf = append(buf, d.Component)
		buf = append(buf, 'A', 'C', 'K')
	}
	buf = append(buf, f)
	buf = append(buf, controlID...)
	buf = append(buf, f)
	buf = append(buf, procID...)
	buf = append(buf, f)
	buf = append(buf, versionID...)
	buf = append(buf, '\r')

	// MSA segment.
	buf = append(buf, 'M', 'S', 'A')
	buf = append(buf, f)
	buf = append(buf, code...)
	buf = append(buf, f)
	buf = append(buf, origControlID...)
	if ab.text != "" {
		buf = append(buf, f)
		buf = append(buf, ab.text...)
	}
	buf = append(buf, '\r')

	// ERR segments.
	for _, e := range errs {
		buf = append(buf, 'E', 'R', 'R')
		buf = append(buf, f) // ERR-1 (deprecated, empty)
		buf = append(buf, f) // ERR-2 start
		buf = append(buf, e.erl...)
		buf = append(buf, f) // ERR-3 (empty)
		buf = append(buf, f) // ERR-4 start
		buf = append(buf, e.sev)
		buf = append(buf, f) // ERR-5 start
		buf = append(buf, e.code...)
		buf = append(buf, f) // ERR-6 (empty)
		buf = append(buf, f) // ERR-7 start
		buf = append(buf, e.desc...)
		buf = append(buf, '\r')
	}

	return buf, nil
}

// errSeverityByte converts a Severity to the ERR-4 character code.
func errSeverityByte(s Severity) byte {
	if s == SeverityWarning {
		return 'W'
	}
	return 'E'
}

// appendERL builds an ERL (Error Location) composite value from a terser-style
// location string. The format is: segment ^ sequence ^ field ^ component ^ subcomponent.
// On parse failure, returns nil (producing an empty ERR-2).
func appendERL(buf []byte, location string, d Delimiters) []byte {
	loc, err := ParseLocation(location)
	if err != nil {
		// Bare segment names like "PID" don't parse (no field number).
		// Try to extract just the segment type if it's 2-3 uppercase letters.
		if len(location) >= 2 && len(location) <= 3 && isUpperAlpha(location) {
			buf = append(buf, location...)
			buf = append(buf, d.Component)
			buf = append(buf, '1') // sequence defaults to 1
			return buf
		}
		return buf
	}

	// ERR-2.1: segment type.
	buf = append(buf, loc.Segment...)
	buf = append(buf, d.Component)

	// ERR-2.2: sequence (1-based). SegmentIndex is 0-based.
	buf = append(buf, strconv.Itoa(loc.SegmentIndex+1)...)
	buf = append(buf, d.Component)

	// ERR-2.3: field number.
	buf = append(buf, strconv.Itoa(loc.Field)...)

	// ERR-2.4: component (only if specified).
	if loc.Component > 0 {
		buf = append(buf, d.Component)
		buf = append(buf, strconv.Itoa(loc.Component)...)

		// ERR-2.5: subcomponent (only if specified).
		if loc.SubComponent > 0 {
			buf = append(buf, d.Component)
			buf = append(buf, strconv.Itoa(loc.SubComponent)...)
		}
	}

	return buf
}

// isUpperAlpha returns true if s contains only A-Z.
func isUpperAlpha(s string) bool {
	for i := 0; i < len(s); i++ {
		if s[i] < 'A' || s[i] > 'Z' {
			return false
		}
	}
	return true
}