msgstore

type AttachmentInfo struct {
	Digest    attach.Digest `json:"digest"`
	Size      int           `json:"size"`
	FirstSeen time.Time     `json:"firstSeen"`

	// Messages is how many stored messages refer to this payload. The number that makes deduplication visible: a
	// document referenced forty times was stored once and would otherwise have been stored forty times.
	Messages int `json:"messages"`
}

type AttachmentStats struct {
	Count int   `json:"count"`
	Bytes int64 `json:"bytes"`

	// References is the total number of message-to-payload references. Reported alongside Count because the gap
	// between them is the saving, and Count alone does not show it.
	References int `json:"references"`

	// Orphans are payloads no stored message refers to. Non-zero is not an error - a message can be pruned before
	// the next sweep - but a number that keeps growing means the sweep is not running.
	Orphans int `json:"orphans"`
}

type Bucket struct {
	Start       time.Time `json:"start"`
	Total       int64     `json:"total"`
	Delivered   int64     `json:"delivered"`
	Filtered    int64     `json:"filtered"`
	Failed      int64     `json:"failed"`
	Unparseable int64     `json:"unparseable"`
}

type Delivery struct {
	Destination string         `json:"destination"`
	Status      DeliveryStatus `json:"status"`
	Attempts    int            `json:"attempts"`
	DurationMS  int64          `json:"durationMs"`
	Error       string         `json:"error,omitempty"`
}

type DeliveryStatus string

type DestinationStats struct {
	Destination string  `json:"destination"`
	Delivered   int64   `json:"delivered"`
	Failed      int64   `json:"failed"`
	Filtered    int64   `json:"filtered"`
	AvgAttempts float64 `json:"avgAttempts"`
	AvgDuration float64 `json:"avgDurationMs"`
}

type ExpressionResult struct {
	// Matches are the messages the expression accepted, newest first.
	Matches []Message `json:"matches"`

	// Examined is how many messages were parsed and tested.
	Examined int `json:"examined"`
	// Available is how many matched the narrowing criteria, so a reader can see what fraction was
	// looked at.
	Available int `json:"available"`
	// Unreadable counts messages that could not be parsed and so could not be tested.
	Unreadable int `json:"unreadable"`
	// Truncated says the examine bound was reached, so there may be matches that were not looked
	// at. Without this a partial answer reads as a complete one.
	Truncated bool `json:"truncated"`

	// Paths lists what the expression looked at, which is a useful check that it says what its
	// author meant.
	Paths []string `json:"paths,omitempty"`
}

type ExpressionSearch struct {
	// TenantID is whose messages are searched. Like every other query here it is unconditional: empty means the default
	// tenant, never every tenant.
	TenantID string

	// Where is a filter expression, in the same language channel filters use.
	Where string

	// Narrowing, applied in SQL before anything is parsed. Using these makes the difference
	// between examining a thousand messages and examining a hundred thousand.
	Channel     string
	MessageType string
	Outcome     Outcome
	Since       time.Time
	Until       time.Time

	// Examine bounds how many messages are parsed. Zero uses a default.
	Examine int
	// Limit bounds how many matches are returned. Zero uses a default.
	Limit int
}

type Flow struct {
	Since    time.Time     `json:"since"`
	Bucket   time.Duration `json:"bucketNanos"`
	Channels []FlowChannel `json:"channels"`
}

type FlowChannel struct {
	Channel string `json:"channel"`
	// Received is the source edge - what arrived at this channel, before any destination.
	Received []Bucket `json:"received"`
	// Strands are the destination edges, sorted by name.
	Strands []Strand `json:"strands"`
}

type HourStat struct {
	// Hour is the index, 0-167. Monday 00:00 is 0.
	Hour int `json:"hour"`

	// Median is the typical count for this hour.
	Median float64 `json:"median"`

	// Low and High are the smallest and largest counts seen.
	//
	// Kept because the spread is what tells somebody whether the median means anything. A feed that has carried
	// between 2 and 900 messages in this hour has no useful normal, and the alert should say so rather than pick a
	// number from the middle and imply confidence.
	Low  int64 `json:"low"`
	High int64 `json:"high"`

	// Floor is the level this hour normally stays above: the 20th percentile of what has been seen.
	//
	// This, not Low, is what decides whether an alert is safe. A shortfall alert fires when traffic is low, so the
	// question is how low the feed goes on an ordinary week - if it routinely dips to a fifth of its median, an alert
	// pitched anywhere useful will fire on ordinary weeks. The true minimum cannot answer that, because one bank
	// holiday drags it to zero and would disqualify a feed that is otherwise perfectly steady.
	Floor float64 `json:"floor"`

	// Observations is how many weeks contributed a count for this hour.
	Observations int `json:"observations"`

	// Silent is how many of those observations were zero.
	//
	// The distinction that matters most. An hour that has been silent nine weeks out of ten is a quiet hour, and a
	// tenth silent week is not news. An hour that has never been silent going quiet is the outage nobody would
	// otherwise hear about, because silence raises no error.
	Silent int `json:"silent"`
}

type IdentityMatch struct {
	Message Message

	// MatchedKind and MatchedValue are why this message is in the result.
	//
	// Returned because a result list of otherwise identical ADT messages gives no clue which
	// field the search hit, and "it matched the account number, not the MRN" changes what the
	// person does next.
	MatchedKind  identity.Kind
	MatchedValue string
}

type IdentityResult struct {
	// Matches is initialised rather than nil so it marshals as an empty array. A client doing
	// .length on null crashes on exactly the search that found nothing.
	Matches []IdentityMatch

	// Total is how many messages matched before the page was taken.
	Total int

	// Indexed reports whether identity indexing is switched on.
	//
	// Returned on every search, because the difference between "no message mentions that
	// number" and "nothing has been indexed" is the difference between a clinical answer and
	// a configuration mistake. Without this a site that never enabled indexing sees an empty
	// result and concludes the patient's messages were never received.
	Indexed bool
}

type IdentitySearch struct {
	// Term is what the person typed: an MRN, a name, a date of birth, an accession.
	Term string

	// Kind narrows to one sort of identifier. Empty searches all of them, which is the
	// default because the person often does not know which sort of number they are holding.
	Kind identity.Kind

	// TenantID scopes the search. Empty means the main tenant, matching Query.
	TenantID string

	// Channel, Since and Until narrow the same way the message list does, so a search can be
	// confined to one feed or one afternoon.
	Channel string
	Since   time.Time
	Until   time.Time

	Limit  int
	Offset int
}

type LastDelivery struct {
	Channel     string     `json:"channel"`
	Destination string     `json:"destination"`
	Delivered   *time.Time `json:"lastDelivered,omitempty"`
	Failed      *time.Time `json:"lastFailed,omitempty"`
	Error       string     `json:"lastError,omitempty"`
}

type Message struct {
	ID      int64  `json:"id"`
	Channel string `json:"channel"`
	// TenantID is which organisation this message belongs to.
	//
	// On the message rather than derived from the channel name, because channel
	// names are not unique across tenants - two clinics both having an "adt-in" is
	// the first thing that happens - so a name could not identify an owner.
	TenantID     string    `json:"tenantId,omitempty"`
	ReceivedAt   time.Time `json:"receivedAt"`
	ControlID    string    `json:"controlId,omitempty"`
	MessageType  string    `json:"messageType,omitempty"`
	TriggerEvent string    `json:"triggerEvent,omitempty"`
	Sender       string    `json:"sender,omitempty"`
	Remote       string    `json:"remote,omitempty"`
	Outcome      Outcome   `json:"outcome"`
	AckCode      string    `json:"ackCode,omitempty"`
	Size         int       `json:"size"`
	DurationMS   int64     `json:"durationMs"`
	Error        string    `json:"error,omitempty"`
	Segments     int       `json:"segments,omitempty"`

	// Raw is the original bytes, loaded only when a single message is fetched.
	// Listing thousands of messages must not drag their payloads along.
	Raw []byte `json:"raw,omitempty"`

	// Deliveries is the per-destination outcome, loaded with a single message.
	Deliveries []Delivery `json:"deliveries,omitempty"`

	// Attachments are the payloads this message carries, loaded with a single
	// message. Described rather than included: the interface needs to say "a 4 MB
	// PDF" without streaming four megabytes to do it.
	Attachments []AttachmentInfo `json:"attachments,omitempty"`

	// AttachmentError explains why Raw could not be fully reassembled, empty when
	// it could. Reported rather than failing the fetch, because a message with an
	// unresolvable payload still records that something arrived.
	AttachmentError string `json:"attachmentError,omitempty"`
}

type MinuteCount struct {
	Channel string
	Minute  time.Time
	Count   int64
}

type Outcome string

type Query struct {
	// TenantID scopes the query to one organisation. Required in multi-tenant operation.
	//
	// A field on the query rather than a separate argument, so it travels with everything else and a caller cannot
	// build a query that forgets it. Empty means the main tenant, which keeps single-tenant callers unchanged - and
	// the alternative, empty meaning "all tenants", is the sort of default that turns one missed line into a
	// disclosure of patient data.
	TenantID string

	Channel      string
	Outcome      Outcome
	MessageType  string
	TriggerEvent string
	ControlID    string
	Sender       string
	// Search matches against the stored payload. It is a substring match, which is
	// slow on a large table and is exactly what somebody needs during an incident
	// when all they have is an accession number.
	Search string
	Since  time.Time
	Until  time.Time
	Limit  int
	Offset int
	// contains filtered or unexported fields
}

type RecentFilter struct {
	// Channels limits it to these channels; empty is every channel.
	Channels []string
	// Types are message_type prefixes (ORU, 999, 277, CT): a message matches when its type starts with one, or for X12
	// contains it among its transaction sets. Empty is every type.
	Types []string
	// Outcomes limits it to these outcomes; empty is every outcome.
	Outcomes []string
	// WithRaw reads the payload too.
	WithRaw bool
	// Limit caps the rows; 0 is 5000.
	Limit int
}

type RecentMessage struct {
	ID         int64
	Channel    string
	Type       string
	Event      string
	Outcome    Outcome
	AckCode    string
	Sender     string
	DurationMS int64
	ReceivedAt time.Time
	// FailedDeliveries counts destinations that failed or are still queued.
	FailedDeliveries int
	Raw              []byte
}

type Recorder struct {
	Store *Store
	Log   *slog.Logger
}

type Rhythm struct {
	// Channel is the feed this describes.
	Channel string `json:"channel"`

	// Hours holds one entry per hour of the week, indexed 0-167, Monday 00:00 UTC at zero.
	//
	// Every hour is present even with no observations, so a caller cannot mistake a gap in the array for a quiet
	// hour. Which of the two it is is the whole question, and Observations is what says.
	Hours [HoursInWeek]HourStat `json:"hours"`

	// Weeks is how many distinct calendar weeks contributed.
	//
	// Reported because it is the honest measure of how much this can be trusted. One week of history means every
	// hour has exactly one observation and the median is that single number, which is not a rhythm - it is last
	// Tuesday.
	Weeks int `json:"weeks"`

	// From and Until bound the history examined.
	From  time.Time `json:"from"`
	Until time.Time `json:"until"`
}

type Stats struct {
	Total     int64            `json:"total"`
	ByOutcome map[string]int64 `json:"byOutcome"`
	ByChannel map[string]int64 `json:"byChannel"`
	ByType    map[string]int64 `json:"byType"`
	// FailedByChannel counts the failed and unparseable messages per channel, for the interface analyst's worst-first list.
	FailedByChannel map[string]int64 `json:"failedByChannel"`
	// RejectedBySender counts the messages this server answered with a negative acknowledgement (AE, AR, CE, CR), per
	// sending application, so a partner sending bad messages shows as one.
	RejectedBySender map[string]int64 `json:"rejectedBySender"`
	OldestKept       *time.Time       `json:"oldestKept,omitempty"`
	NewestKept       *time.Time       `json:"newestKept,omitempty"`
	StoredBytes      int64            `json:"storedBytes"`
}

type Store struct {

	// RetentionDays bounds how long messages are kept. Zero means forever, which
	// is a choice an operator should have to make deliberately rather than get by
	// default.
	RetentionDays int

	// StorePayloads controls whether the original bytes are kept. Turning it off
	// keeps counts and outcomes while storing no clinical content, which is what
	// a deployment that cannot hold PHI at rest needs.
	StorePayloads bool

	// IndexIdentity controls whether identifiers are extracted from payloads into a
	// searchable index, so a message can be found by MRN or by name whatever format it
	// arrived in.
	//
	// This is a privacy decision and not only a performance one. The identifiers are already
	// in this database inside the payload column, so indexing them adds no data - but it does
	// make them enumerable, and a database that could previously only be grepped for a
	// number somebody already had can now be asked to list patients. That is a decision for
	// the site.
	//
	// Independent of StorePayloads except in one direction, enforced in indexIdentity below:
	// an installation that keeps no payloads is not given an identity index either, because
	// there the extraction would be retaining clinical content that the site chose not to
	// retain.
	IndexIdentity bool

	// PayloadDays is how long message bodies are kept, when set.
	//
	// Zero means half the retention window, which is what this did before the value
	// was configurable - so an installation that says nothing keeps behaving as it did.
	PayloadDays int

	// RetentionDaysFn, StorePayloadsFn and PayloadDaysFn supersede the fields above when set.
	//
	// They exist so these can be changed while the server runs. Reading the fields
	// directly while something else writes them is a data race, and the settings
	// store already holds a lock around its values - so the safe arrangement is to
	// ask it each time rather than copy the value in at startup.
	//
	// Assigned once before serving begins, like the fields they replace. It is the
	// values behind them that change, not the functions.
	RetentionDaysFn func() int
	StorePayloadsFn func() bool
	PayloadDaysFn   func() int
	IndexIdentityFn func() bool
	// contains filtered or unexported fields
}

type Strand struct {
	Channel     string `json:"channel"`
	Destination string `json:"destination"`
	// Buckets covers the full window, zero-filled.
	Buckets []Bucket `json:"buckets"`
}

type SubjectMessage struct {
	ID         int64     `json:"id"`
	Channel    string    `json:"channel"`
	ReceivedAt time.Time `json:"receivedAt"`
	ControlID  string    `json:"controlId,omitempty"`
	Type       string    `json:"type,omitempty"`
	// Matched is the identifier it was found by, as the index holds it.
	Matched string `json:"matched"`
}