Documentation
¶
Overview ¶
Package zeitreihermodels holds the hand-written public data models of the Zeitreiher API, version 1.
Zeitreiher is a read-only API over SAP IS-U EDM profile values (Lastgänge). The contract is the JSON form of the types in this package, pinned by the shared fixtures in testdata/, which the Go and the Python models both parse and round-trip. The gRPC contract lives in proto/zeitreiher/v1.
The package lives at the repository root; its major version follows Go module versioning, so a breaking v2 is the module github.com/hochfrequenz/zeitreiher-models/v2 (spec §3.4).
Nothing in this package is generated. Every type validates itself when it is unmarshalled and refuses to marshal when it is invalid, so a value that leaves or enters a program through these types always satisfies the contract:
- Request timestamps are RFC 3339 with whole seconds and an explicit offset (Z or ±hh:mm). Timestamps without an offset and the "unknown offset" -00:00 are rejected.
- Response timestamps are RFC 3339 with whole seconds in UTC (Z).
- Intervals are half-open: [from, to), and from must be before to.
- Values are decimal strings, already scaled, in shortest canonical form ("160", "0.022"; never "160.0"), never JSON numbers.
- Error codes are strict on write, lenient on read: unknown snake_case codes parse, only the public codes are written.
- Requests reject unknown keys; responses ignore them, so additive server changes do not break older clients.
Index ¶
- Constants
- Variables
- func MarshalRecord(rec Record) ([]byte, error)
- func ReadRecords(r io.Reader) iter.Seq2[Record, error]
- func WriteRecord(w io.Writer, rec Record) error
- type Assignment
- type Decimal
- type EndRecord
- type ErrorDetail
- type ErrorEnvelope
- type ErrorRecord
- type QueryRequest
- type Record
- type RecordErrorCode
- type RequestErrorCode
- type ResolveRequest
- type ResolveResponse
- type ResolveResult
- type ResultError
- type Selector
- type SeriesRecord
- type SystemInfo
- type ValueRecord
- type Version
- type VersionSelector
- type VersionedAssignment
- type VersionsRequest
- type VersionsResponse
- type VersionsResult
- type WindowRequest
Constants ¶
const ( RecordTypeSeries = "series" RecordTypeValue = "value" RecordTypeError = "error" RecordTypeEnd = "end" )
Record types, the value of the "type" key of every NDJSON line.
const ( SelectorByProfile = "profile" SelectorByMaLo = "malo" )
Selector kinds known to every Zeitreiher installation. Any other kind is a custom selector that a customer resolver implements.
Variables ¶
var ErrMissingEnd = errors.New("response stream does not end with an end record")
ErrMissingEnd is returned by ReadStream when a response does not end with exactly one end record. Such a response was cut off and must be treated as a failure (spec §4.3).
Functions ¶
func MarshalRecord ¶
MarshalRecord validates rec and returns its JSON form without a trailing newline.
func ReadRecords ¶
ReadRecords yields the records of an NDJSON stream. Every line must hold one record; the final newline is optional. Blank lines and carriage returns are errors. Iteration stops after the first error. ReadRecords does not check for the end record; use ReadStream for complete responses.
Types ¶
type Assignment ¶
Assignment is one profile assignment of a resolve result (spec §4.4). Either From and To are set (the assignment, cut to the request window) or Error is set (e.g. access_denied); an assignment with an error may still carry its window.
func (Assignment) MarshalJSON ¶
func (a Assignment) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the assignment.
func (*Assignment) UnmarshalJSON ¶
func (a *Assignment) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the assignment; unknown keys (such as versions) are ignored.
type Decimal ¶
type Decimal string
Decimal is an already-scaled decimal number in its shortest canonical string form, e.g. "160", "0.022", "25.25" or "-3.5".
Values are strings on the wire so that no client loses precision by parsing them as floats. The accepted syntax is an optional minus, an integer part without leading zeros and an optional fractional part without trailing zeros: ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$, and the fraction must not end in 0. Exponents, a plus sign, negative zero, trailing zeros ("160.0", "0.0220") and JSON numbers are rejected: after parsing, 160.0 and 160 are the same number, so the wire carries one spelling.
func (Decimal) MarshalJSON ¶
MarshalJSON writes d as a JSON string after validating it.
func (*Decimal) UnmarshalJSON ¶
UnmarshalJSON accepts a JSON string with a valid decimal only.
type EndRecord ¶
type EndRecord struct {
// Series, Values and Errors count the series, value and error records on this page only (not
// the whole result). A series record re-sent at the start of a continuation page counts again.
Series, Values, Errors int
// Next is the cursor for the next page, or nil when the result is complete.
Next *string
}
EndRecord closes a successful response. A response without an end record is incomplete and must be treated as a failure.
func (*EndRecord) MarshalJSON ¶
MarshalJSON validates and writes the record; a nil Next is written as null.
func (*EndRecord) UnmarshalJSON ¶
UnmarshalJSON parses and validates the record.
type ErrorDetail ¶
type ErrorDetail struct {
// Code is stable and machine-readable; clients switch on it, never on Message.
Code RequestErrorCode `json:"code"`
// Message is a human-readable explanation.
Message string `json:"message"`
// RequestID correlates the response with server logs; empty when unknown (omitted on the wire).
RequestID string `json:"request_id,omitempty"`
}
ErrorDetail is the content of an ErrorEnvelope.
func (*ErrorDetail) UnmarshalJSON ¶
func (d *ErrorDetail) UnmarshalJSON(b []byte) error
UnmarshalJSON enforces the presence rules of the detail.
type ErrorEnvelope ¶
type ErrorEnvelope struct {
Error ErrorDetail `json:"error"`
}
ErrorEnvelope is the body of every failed (non-2xx) HTTP response: {"error":{"code":"…","message":"…","request_id":"…"}}. It has the shape of btpingo.ErrorEnvelope.
func (ErrorEnvelope) MarshalJSON ¶
func (e ErrorEnvelope) MarshalJSON() ([]byte, error)
MarshalJSON validates before writing.
func (*ErrorEnvelope) UnmarshalJSON ¶
func (e *ErrorEnvelope) UnmarshalJSON(b []byte) error
UnmarshalJSON enforces the presence rules of the envelope.
func (ErrorEnvelope) Validate ¶
func (e ErrorEnvelope) Validate() error
Validate checks the envelope.
type ErrorRecord ¶
type ErrorRecord struct {
// Selector is the index of the request selector the problem belongs to.
Selector int
// Select echoes the request selector.
Select Selector
// Profile is set where the problem concerns one profile assignment; empty otherwise.
Profile string
// Code says what went wrong; see the RecordError* constants.
Code RecordErrorCode
}
ErrorRecord reports a per-selector or per-assignment problem; the stream continues.
func (*ErrorRecord) MarshalJSON ¶
func (r *ErrorRecord) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the record; an empty Profile is omitted.
func (*ErrorRecord) RecordType ¶
func (*ErrorRecord) RecordType() string
RecordType returns "error".
func (*ErrorRecord) UnmarshalJSON ¶
func (r *ErrorRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the record.
type QueryRequest ¶
type QueryRequest struct {
// Select lists one or more selectors; results refer to them by index.
Select []Selector
// From and To bound the half-open window [From, To). Their offsets are kept on the wire.
From, To time.Time
// Version is optional; nil means the current values.
Version *VersionSelector
// Interval is optional, e.g. "PT15M"; empty means the profile's own interval.
Interval string
// Unit is optional, a canonical unit code (UN/ECE Rec. 20) such as "KWH", "MWH" or "KVR"; the server
// maps it to the customer's SAP unit. Empty means the profile's own unit.
Unit string
// Cursor continues a previous response (its end record's next); empty starts at the beginning.
Cursor string
}
QueryRequest is the body of POST /api/v1/series/query (and QUERY /api/v1/series), spec §4.1.
func (QueryRequest) MarshalJSON ¶
func (q QueryRequest) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the request; unset optional fields are omitted.
func (*QueryRequest) UnmarshalJSON ¶
func (q *QueryRequest) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the request. Unknown keys are rejected; null optional fields count as absent.
type Record ¶
type Record interface {
// RecordType returns the value of the "type" key.
RecordType() string
// Validate checks the record.
Validate() error
// contains filtered or unexported methods
}
Record is one line of a query response (NDJSON) and one gRPC Record message. It is one of *SeriesRecord, *ValueRecord, *ErrorRecord or *EndRecord.
func ParseRecord ¶
ParseRecord parses one NDJSON line (without its trailing newline) into a record.
type RecordErrorCode ¶
type RecordErrorCode string
RecordErrorCode is a per-selector or per-assignment error code. It appears in NDJSON error records and in the error objects of resolve/versions results; the rest of the response continues.
const ( RecordErrorSelectorNotFound RecordErrorCode = "selector_not_found" RecordErrorNoAssignment RecordErrorCode = "no_assignment" RecordErrorUnknownSelector RecordErrorCode = "unknown_selector" RecordErrorBadSelector RecordErrorCode = "bad_selector" RecordErrorAccessDenied RecordErrorCode = "access_denied" RecordErrorProfileNotFound RecordErrorCode = "profile_not_found" RecordErrorProfileTimeZoneMissing RecordErrorCode = "profile_time_zone_missing" RecordErrorIntervalSizeUnsupported RecordErrorCode = "interval_size_unsupported" RecordErrorWindowUnaligned RecordErrorCode = "window_unaligned" RecordErrorAssignmentUnaligned RecordErrorCode = "assignment_unaligned" RecordErrorVersionNotFound RecordErrorCode = "version_not_found" // RecordErrorVersionDeleted: the requested {"number":N} names a version that is flagged as deleted // (it is still listed by the versions endpoint, with deleted: true). RecordErrorVersionDeleted RecordErrorCode = "version_deleted" RecordErrorConversionNotAllowed RecordErrorCode = "conversion_not_allowed" RecordErrorAmbiguousLocalTime RecordErrorCode = "ambiguous_local_time" RecordErrorBadiFailed RecordErrorCode = "badi_failed" )
Record-level error codes (spec §4.3, consolidated list).
func AllRecordErrorCodes ¶
func AllRecordErrorCodes() []RecordErrorCode
AllRecordErrorCodes returns every record-level error code in specification order.
func (RecordErrorCode) IsKnown ¶
func (c RecordErrorCode) IsKnown() bool
IsKnown reports whether c is one of the record-level codes this version of the models knows. Parsing accepts unknown snake_case codes so that a newer server does not break older clients.
func (RecordErrorCode) MarshalJSON ¶
func (c RecordErrorCode) MarshalJSON() ([]byte, error)
MarshalJSON writes only the public codes: error codes are strict on write, lenient on read.
func (*RecordErrorCode) UnmarshalJSON ¶
func (c *RecordErrorCode) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts any snake_case code; use IsKnown to tell known from unknown codes.
func (RecordErrorCode) Validate ¶
func (c RecordErrorCode) Validate() error
Validate checks the code syntax (snake_case). It accepts unknown codes, as parsing does.
type RequestErrorCode ¶
type RequestErrorCode string
RequestErrorCode is a request-level error code. It appears in the error envelope of an HTTP response that failed as a whole (before any NDJSON record was written).
const ( RequestErrorInvalidRequest RequestErrorCode = "invalid_request" RequestErrorForbidden RequestErrorCode = "forbidden" RequestErrorNotFound RequestErrorCode = "not_found" RequestErrorMethodNotAllowed RequestErrorCode = "method_not_allowed" RequestErrorRequestTooLarge RequestErrorCode = "request_too_large" RequestErrorUpstreamUnreachable RequestErrorCode = "upstream_unreachable" RequestErrorInternal RequestErrorCode = "internal" RequestErrorCursorInvalid RequestErrorCode = "cursor_invalid" RequestErrorCursorMismatch RequestErrorCode = "cursor_mismatch" RequestErrorCursorExpired RequestErrorCode = "cursor_expired" RequestErrorCursorStale RequestErrorCode = "cursor_stale" RequestErrorUpstreamTimeout RequestErrorCode = "upstream_timeout" )
Request-level error codes (spec §4.3, consolidated list). The first eight are btpingo's request-level vocabulary (btpingo.ErrorCode in httperr.go), shared by the Hochfrequenz BTP services; the cursor codes and upstream_timeout are Zeitreiher's own.
func AllRequestErrorCodes ¶
func AllRequestErrorCodes() []RequestErrorCode
AllRequestErrorCodes returns every request-level error code in specification order.
func (RequestErrorCode) IsKnown ¶
func (c RequestErrorCode) IsKnown() bool
IsKnown reports whether c is one of the request-level codes this version of the models knows. Parsing accepts unknown snake_case codes so that a newer server does not break older clients.
func (RequestErrorCode) MarshalJSON ¶
func (c RequestErrorCode) MarshalJSON() ([]byte, error)
MarshalJSON writes only the public codes: error codes are strict on write, lenient on read.
func (*RequestErrorCode) UnmarshalJSON ¶
func (c *RequestErrorCode) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts any snake_case code; use IsKnown to tell known from unknown codes.
func (RequestErrorCode) Validate ¶
func (c RequestErrorCode) Validate() error
Validate checks the code syntax (snake_case). It accepts unknown codes, as parsing does.
type ResolveRequest ¶
type ResolveRequest = WindowRequest
ResolveRequest is the body of POST /api/v1/series/resolve.
type ResolveResponse ¶
type ResolveResponse struct {
Results []ResolveResult `json:"results"`
}
ResolveResponse is the body of a successful resolve response: {"results":[…]}.
func (ResolveResponse) MarshalJSON ¶
func (r ResolveResponse) MarshalJSON() ([]byte, error)
MarshalJSON writes {"results":[…]}; nil Results is written as [].
func (*ResolveResponse) UnmarshalJSON ¶
func (r *ResolveResponse) UnmarshalJSON(b []byte) error
UnmarshalJSON parses the response.
type ResolveResult ¶
type ResolveResult struct {
Selector int
Select Selector
Assignments []Assignment
Error *ResultError
}
ResolveResult is the outcome for one request selector of the resolve endpoint: either Assignments (possibly empty) or Error.
func (ResolveResult) MarshalJSON ¶
func (r ResolveResult) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the result.
func (*ResolveResult) UnmarshalJSON ¶
func (r *ResolveResult) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the result.
type ResultError ¶
type ResultError struct {
Code RecordErrorCode `json:"code"`
}
ResultError is the error object of a resolve/versions result or assignment: {"code":"…"}.
func (ResultError) MarshalJSON ¶
func (r ResultError) MarshalJSON() ([]byte, error)
MarshalJSON validates before writing.
func (*ResultError) UnmarshalJSON ¶
func (r *ResultError) UnmarshalJSON(b []byte) error
UnmarshalJSON enforces the presence rules.
type Selector ¶
Selector names the business object whose profile assignments are queried. It is a union over By:
{"by":"profile","profile":"50000000000056"} – a profile number
{"by":"malo","malo":"87253749908"} – a market location
{"by":"<name>","params":{"<key>":"<string>"}} – a customer resolver
Build selectors with ProfileSelector, MaLoSelector or CustomSelector. Only the fields of the variant named by By are used; the others must be empty.
func CustomSelector ¶
CustomSelector selects via a customer resolver named by. params may be nil.
func MaLoSelector ¶
MaLoSelector selects the profiles assigned to a market location.
func ProfileSelector ¶
ProfileSelector selects a profile by number (leading zeros allowed).
func (Selector) MarshalJSON ¶
MarshalJSON writes the keys of the variant only, after validating with the request rules.
func (*Selector) UnmarshalJSON ¶
UnmarshalJSON accepts exactly the keys of the variant named by "by" (request rules).
type SeriesRecord ¶
type SeriesRecord struct {
// Series numbers the series of a response, starting at 1 and continuing across pages.
Series int
// Selector is the index of the request selector this series belongs to.
Selector int
// Select echoes the request selector (profile numbers without leading zeros).
Select Selector
// Profile is the SAP profile number, without leading zeros.
Profile string
// Role is the role of the profile assignment (SAP EPROFASS role, e.g. "0001"), or nil when the series
// was not resolved through a role (e.g. by: profile). The Resolver BAdI may override it.
Role *string
// From and To bound the assignment, cut to the request window.
From, To time.Time
// Unit is the canonical unit code (UN/ECE Rec. 20, e.g. "KWH") of the delivered values (after any
// conversion), or nil when the SAP unit has no mapping. The series is delivered either way.
Unit *string
// UnitRaw is the SAP unit key (T006 MSEHI) as SAP delivers it, mapped or not: any non-empty text of
// at most 30 characters without control characters.
UnitRaw string
// Interval is that of the delivered values (after any conversion).
Interval string
// Attributes come from the customer's Metadata BAdI; never nil after unmarshalling.
Attributes map[string]string
// Versions lists the profile versions overlapping the series; never nil after unmarshalling.
Versions []Version
}
SeriesRecord opens a series: one profile assignment of one selector, cut to the request window.
func (*SeriesRecord) MarshalJSON ¶
func (r *SeriesRecord) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the record with "type" first; a nil Role or Unit is written as null.
func (*SeriesRecord) RecordType ¶
func (*SeriesRecord) RecordType() string
RecordType returns "series".
func (*SeriesRecord) UnmarshalJSON ¶
func (r *SeriesRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the record.
type SystemInfo ¶
type SystemInfo struct {
// ServiceVersion is the version of the Zeitreiher service (Go).
ServiceVersion string
// AbapPackageVersion is the version of the ABAP package /HFQ/ZEITREIHER.
AbapPackageVersion string
// SID and Client identify the SAP system.
SID string
Client string
// Release is the SAP release.
Release string
// BusinessTimeZone is the configured SAP time zone code, e.g. "CET".
BusinessTimeZone string
// Intervals lists the supported request intervals, e.g. ["PT15M","PT60M"].
Intervals []string
}
SystemInfo is the body of GET /api/v1/system (spec §4.4).
func (SystemInfo) MarshalJSON ¶
func (s SystemInfo) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the system info.
func (*SystemInfo) UnmarshalJSON ¶
func (s *SystemInfo) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the system info.
type ValueRecord ¶
type ValueRecord struct {
// Series is the number of the series record this value belongs to.
Series int
// From and To bound the value's interval.
From, To time.Time
// Value is the already-scaled decimal value.
Value Decimal
// Status holds the active SAP status codes overlapping the interval, sorted; never nil after
// unmarshalling.
Status []string
// Version is the source of the value: the number of the stored version row it came from, or nil
// when it is a current value. With {"number":N} a series mixes both: current values overlaid with
// the stored values of versions >= N (the lowest wins), only inside N's covered range.
Version *int
}
ValueRecord is one value of a series for the half-open interval [From, To).
func (*ValueRecord) MarshalJSON ¶
func (r *ValueRecord) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the record; a nil Version is written as null.
func (*ValueRecord) RecordType ¶
func (*ValueRecord) RecordType() string
RecordType returns "value".
func (*ValueRecord) UnmarshalJSON ¶
func (r *ValueRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the record.
type Version ¶
type Version struct {
// Number is the SAP version number (CVERSNO), at least 1.
Number int
// From and To bound the covered range [From, To); To is nil for an open end.
From time.Time
To *time.Time
// CreatedAt is the creation instant; nil when it cannot be determined, then CreatedAtUnknown is true.
CreatedAt *time.Time
CreatedAtUnknown bool
// Reason and Description are SAP's VERSREASON and VERSDESCR; either may be empty.
Reason string
Description string
// Deleted is true for versions flagged as deleted in SAP. They are still listed; querying their
// values gives an error record with code version_deleted.
Deleted bool
}
Version describes one EDM profile version that overlaps a series (spec §4.2, §5).
func (Version) MarshalJSON ¶
MarshalJSON validates and writes the version; To and CreatedAt are written as null when nil.
func (*Version) UnmarshalJSON ¶
UnmarshalJSON parses and validates the version.
type VersionSelector ¶
VersionSelector chooses which values a query returns (spec §5). Exactly one form is set:
{"current":{}} – the current values (the default when omitted)
{"number":3} – version 3 as SAP rebuilds it: the current values overlaid with the stored
values of versions >= 3 (the lowest version wins), only inside version 3's
covered range; outside it the series has gaps
v1 has no as-of selector; {"as_of":…} is rejected as an unknown key. Build it with CurrentVersion or VersionNumber.
func CurrentVersion ¶
func CurrentVersion() VersionSelector
CurrentVersion selects the current values.
func VersionNumber ¶
func VersionNumber(n int) VersionSelector
VersionNumber selects version n (see VersionSelector).
func (VersionSelector) MarshalJSON ¶
func (v VersionSelector) MarshalJSON() ([]byte, error)
MarshalJSON writes the single set form.
func (*VersionSelector) UnmarshalJSON ¶
func (v *VersionSelector) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts exactly one of the two forms.
func (VersionSelector) Validate ¶
func (v VersionSelector) Validate() error
Validate checks that exactly one form is set and that it is valid.
type VersionedAssignment ¶
type VersionedAssignment struct {
Assignment
Versions []Version
}
VersionedAssignment is one profile assignment of a versions result: an Assignment plus the overlapping versions. Versions is written as [] when there are none and omitted with an error.
func (VersionedAssignment) MarshalJSON ¶
func (v VersionedAssignment) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the assignment.
func (*VersionedAssignment) UnmarshalJSON ¶
func (v *VersionedAssignment) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the assignment; versions is required unless error is set.
type VersionsRequest ¶
type VersionsRequest = WindowRequest
VersionsRequest is the body of POST /api/v1/series/versions.
type VersionsResponse ¶
type VersionsResponse struct {
Results []VersionsResult `json:"results"`
}
VersionsResponse is the body of a successful versions response: {"results":[…]}.
func (VersionsResponse) MarshalJSON ¶
func (r VersionsResponse) MarshalJSON() ([]byte, error)
MarshalJSON writes {"results":[…]}; nil Results is written as [].
func (*VersionsResponse) UnmarshalJSON ¶
func (r *VersionsResponse) UnmarshalJSON(b []byte) error
UnmarshalJSON parses the response.
type VersionsResult ¶
type VersionsResult struct {
Selector int
Select Selector
Assignments []VersionedAssignment
Error *ResultError
}
VersionsResult is the outcome for one request selector of the versions endpoint.
func (VersionsResult) MarshalJSON ¶
func (r VersionsResult) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the result.
func (*VersionsResult) UnmarshalJSON ¶
func (r *VersionsResult) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the result.
type WindowRequest ¶
WindowRequest is the body of the resolve and versions endpoints (spec §4.4): selectors and a window, nothing else.
func (WindowRequest) MarshalJSON ¶
func (w WindowRequest) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the request.
func (*WindowRequest) UnmarshalJSON ¶
func (w *WindowRequest) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the request; unknown keys (e.g. version, cursor) are rejected.
func (WindowRequest) Validate ¶
func (w WindowRequest) Validate() error
Validate checks the request.