Skip to content

feat(datacustodian): Batch/Subscription feed of a subscription's usage data (#279) - #282

Open
dfcoffin wants to merge 8 commits into
mainfrom
feature/279-dc-batch-subscription
Open

dfcoffin wants to merge 8 commits into
mainfrom
feature/279-dc-batch-subscription

Conversation

@dfcoffin

@dfcoffin dfcoffin commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Closes #279.

Endpoint

GET /espi/1_1/resource/Batch/Subscription/{subscriptionId} returns one Atom feed of the subscription's usage data.

  • Entries, per UsagePoint the customer selected: the UsagePoint; each MeterReading with its ReadingType (once per feed) and IntervalBlocks; UsageSummaries; ElectricPowerQualitySummaries; LocalTimeParameters.
  • Links: subscription-scoped hrefs; each entry has self, up and related links (related only when the target is in the feed). The feed's self link type is always espi-feed/Subscription, also when empty (the link-type note from the feat(common): ESPI resources inside atom:content, and XSD validation of ESPI XML (#197) #280 review).
  • Access (ScopeResolver.canReadSubscription): the DC admin reads any subscription; a customer token reads only the subscription named in its resourceURI. Anything else, including the Third Party's FB=34_35 client token, gets 403 whether or not the subscription exists. Unknown subscription for the admin: 404.
  • UsagePoints by commodity: a customer token gets only the UsagePoints whose ServiceCategory a granted commodity Function Block covers (from FunctionBlock's service kind, matched to the UsagePoint by ServiceKind.of, the mapping the consent screen also uses): FB_5–FB_9 electricity, FB_10 gas, FB_11 water. FB_29 (temperature) covers none until Define FB_29 (Temperature Interval Metering) query requirements #283 defines it. The URL rule for this endpoint needs FB_4 plus one of FB_5–FB_11 (or admin): FB_4 alone, or FB_4 with only FB_29, is a 403.
  • Summaries: UsageSummaries need FB_15/16/27/28, ElectricPowerQualitySummaries need FB_17. The lists live in UsageFunctionBlockAuthorities, now also used by SecurityConfiguration.
  • Which data is returned (IntervalBlocks, UsageSummaries, ElectricPowerQualitySummaries; each interval runs from start to start + duration):
    • published-min/published-max select those whose interval overlaps the range; updated-min/updated-max select by atom:updated. A malformed xs:dateTime, or a -min after its -max, is a 400.
    • With neither published-min nor published-max, the default is the last 24 hours by overlap, plus each UsagePoint's most recent UsageSummary and ElectricPowerQualitySummary (summary intervals rarely line up with a 24-hour window).
    • HistoryLength (REQ.21.6.1.2.1: the history available, in seconds) is a ceiling, not a selection: nothing that ended before now minus that many seconds is returned, whatever the range asks for. Every scope that grants a usage-data FB (FB_4, commodity, summary or power quality) counts, and the shortest applies; customer-data scopes do not; an FB scope that does not parse is a 403.
    • A resource without an interval is kept. BlockDuration filters nothing.
  • Order: UsagePoints and MeterReadings by id; blocks and summaries by interval start. ReadingType and LocalTimeParameters appear once per feed, even when shared.
  • The controller has no produces: the DC default content type is JSON, so an XML-only mapping answered 406 to requests without Accept. The response is always application/atom+xml.

XML defects found by validating the feed against espi.xsd

  1. DateTimeIntervalDto wrote start/duration unqualified and in the wrong order (invalid IntervalBlocks, readings and summaries). Now espi namespace, duration then start.
  2. New CustomerDateTimeIntervalDto (cust namespace) for CustomerAgreement.validityInterval, so customer feeds don't carry espi elements.
  3. The DateTimeInterval embeddable lost its JAXB annotations (CLAUDE.md known defect); after fix 1 they declared a duplicate XML type and broke the DC's JAXB context.
  4. TimeConfigurationDto is written as espi:LocalTimeParameters (espi.xsd has no global TimeConfiguration element); an empty tariffRiderRefs is omitted (the XSD needs at least one tariffRiderRef).

ServiceCategory errors are still tolerated by the feed tests; that fix is #278.

Tests

  • BatchSubscriptionIntegrationTest (7): certified entry order and links with XSD validation, FB gating, the 24-hour default and latest-summary rule, published/updated ranges, the HistoryLength ceiling, chronological order, a shared LocalTimeParameters, an unreadable scope (403), a malformed parameter (400), UsagePoints by commodity FB, FB_4 alone and FB_4 + FB_29 refused, 403 cases, client-token refusal, admin access/404, empty feed.
  • ScopeResolverTest: canReadSubscription, espiScope.
  • Full Docker suite (WSL): handoff 22, common 918, DC 235 (re-run after both reviews' fixes), TP 123 (2 skipped), all passing.

Follow-ups: #283 (FB_29 temperature), #284 (Authorization Server HistoryLength defaults to seconds), #285 (select in the database, stream the feed).

🤖 Generated with Claude Code

dfcoffin and others added 3 commits November 18, 2026 07:25
…e data (#279)

GET /espi/1_1/resource/Batch/Subscription/{subscriptionId} returns one Atom
feed (espi-feed/Subscription) of the subscription's UsagePoints with their
MeterReadings, ReadingTypes, IntervalBlocks, UsageSummaries,
ElectricPowerQualitySummaries and LocalTimeParameters, with self/up/related
links scoped to the subscription.

- Access: the DC admin, or a customer token whose resourceURI names exactly
  that subscription (ScopeResolver.canReadSubscription); the FB=34_35 client
  token and everything else get 403.
- Summaries only with their Function Blocks (UsageFunctionBlockAuthorities,
  shared with SecurityConfiguration); IntervalBlocks older than the scope's
  HistoryLength are left out.

XML defects found by validating the feed against espi.xsd:
- DateTimeIntervalDto: espi namespace, duration before start.
- CustomerDateTimeIntervalDto (cust namespace) for CustomerAgreement.
- DateTimeInterval embeddable: JAXB annotations removed (duplicate XML type).
- TimeConfigurationDto is written as espi:LocalTimeParameters.
- An empty tariffRiderRefs element is omitted.

ServiceCategory errors (#278) are still tolerated by the feed tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ption (#279)

HistoryLength limited only IntervalBlocks, so a token granted a short
history still received UsageSummaries and ElectricPowerQualitySummaries for
any period. One cutoff now applies to every time-bounded resource in the
feed: an IntervalBlock's interval, a UsageSummary's billingPeriod and an
ElectricPowerQualitySummary's summaryInterval must end after
now - HistoryLength. A resource without an interval is kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ling, review fixes (#279)

Data selection:
- published-min/max select IntervalBlocks, UsageSummaries and
  ElectricPowerQualitySummaries whose interval (start to start + duration)
  overlaps the range; updated-min/max select by atom:updated.
- Without published-min/max the default is the last 24 hours, by overlap,
  plus each UsagePoint's most recent UsageSummary and EPQS.
- HistoryLength is a ceiling, not a selection: nothing that ended before
  now - HistoryLength is returned, whatever the range asks for.
- A malformed xs:dateTime parameter is a 400.

Review fixes:
- A LocalTimeParameters shared by several UsagePoints is one entry.
- Every FB scope is parsed; one that does not parse is a 403 instead of
  "no HistoryLength", and the shortest HistoryLength applies.
- UsagePoints and MeterReadings are sorted by id, time-bounded resources
  by interval start, so the feed is chronological and stable.
- hasAdminAuthority reuses hasAuthority; the unused setClock is removed
  and the clock is final.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dfcoffin and others added 2 commits November 18, 2026 19:38
…tion Block (#279)

A customer token now gets only the UsagePoints whose ServiceCategory one of
its commodity Function Blocks covers, from each FB's service kind: FB_5 to
FB_9 electricity, FB_10 gas, FB_11 water. FB_29 (temperature) covers none
until #283 defines it. The DataCustodian admin still sees every UsagePoint.

Batch/Subscription now needs only FB_4 (or admin): a token with interval
metering and no commodity FB gets an empty feed instead of a 403. The other
usage-data URLs still need FB_4 plus a commodity FB.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ity, gas or water FB (#279)

Reverses the FB_4-only rule: the endpoint now needs FB_4 and one of
FB_5-FB_9 (electricity), FB_10 (gas) or FB_11 (water), or the DataCustodian
admin. FB_4 alone and FB_4 with only FB_29 (temperature, #283) get 403.
UsageFunctionBlockAuthorities.SERVICE_COMMODITY lists those FBs and also
drives the UsagePoint service-category selection.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
dfcoffin and others added 3 commits November 18, 2026 21:27
…#279)

- HistoryLength is a number of months (#284): the ceiling is now minus that
  many calendar months (UTC), matching the Authorization Server's
  HistoryLength=13 scopes.
- Only usage scopes (with FB_4) set the ceiling; a customer-data scope's
  HistoryLength no longer limits usage data.
- The client access token scope FB=34_35 is recognised in any case.
- ServiceKind.of(ServiceCategory) is the one UsagePoint-to-ServiceKind
  mapping, by espi.xsd code; the consent screen and the feed both use it.
- A -min query parameter after its -max is a 400.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ly FB_4 scopes (#279)

A summary-only scope such as FB=16_17;HistoryLength=1 was skipped because
it lacks FB_4, so its summaries got the longer HistoryLength of another
scope. The ceiling now comes from every scope that grants a usage-data FB
(UsageFunctionBlockAuthorities.USAGE_DATA: FB_4, commodities, summaries,
power quality); only scopes without one, such as customer-data scopes, are
left out.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…#279)

REQ.21.6.1.2.1 and REQ.21.4.2.1.3.3 define HistoryLength as "the amount of
historical information available from the Data Custodian in seconds", and
every HistoryLength in the issued CMD certificates' ApplicationInformation
scopes is in seconds. The ceiling is again now minus that many seconds;
#284 tracks the Authorization Server defaults (HistoryLength=13 / 7).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

DC: serve Batch/Subscription/{id} (the customer token's resourceURI) as one subscription-scoped Atom feed

1 participant