From 1fd810fda46e009e4dea0949a796b72117c1cfd0 Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 07:25:54 -0500
Subject: [PATCH 1/9] feat(datacustodian): Batch/Subscription feed of a
subscription's usage 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
---
CLAUDE.md | 5 +-
.../domain/common/DateTimeInterval.java | 16 +-
.../common/dto/atom/UsageAtomEntryDto.java | 3 +-
.../dto/common/DateTimeIntervalDto.java | 16 +-
.../dto/customer/CustomerAgreementDto.java | 3 +-
.../customer/CustomerDateTimeIntervalDto.java | 55 +++
.../dto/usage/TimeConfigurationDto.java | 6 +-
.../mapper/usage/TariffRiderRefMapper.java | 6 +-
.../common/service/BaseExportService.java | 67 +++-
.../customer/CustomerAgreementDtoTest.java | 6 +-
.../dto/usage/TimeConfigurationDtoTest.java | 23 +-
.../config/SecurityConfiguration.java | 16 +-
.../config/UsageFunctionBlockAuthorities.java | 68 ++++
.../web/api/BatchSubscriptionController.java | 121 ++++++
.../web/api/SubscriptionFeedAssembler.java | 233 +++++++++++
.../web/api/scope/ScopeResolver.java | 69 ++++
.../api/BatchSubscriptionIntegrationTest.java | 367 ++++++++++++++++++
.../web/api/scope/ScopeResolverTest.java | 39 ++
18 files changed, 1053 insertions(+), 66 deletions(-)
create mode 100644 openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java
create mode 100644 openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
create mode 100644 openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
create mode 100644 openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
create mode 100644 openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
diff --git a/CLAUDE.md b/CLAUDE.md
index 0a065dde..ce8ab951 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -129,7 +129,7 @@ Note: ServiceSupplier has an entity, DTO, and mapper but no repository or servic
### REST API Structure
REST controllers are in `openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/`:
-- **web/api/** - ESPI RESTful API endpoints. GET-only (feed + entry) for ApplicationInformation, Authorization, Customer, CustomerAccount, UsagePoint, MeterReading, ReadingType, IntervalBlock, UsageSummary, ElectricPowerQualitySummary. `web/api/scope/` holds `ScopeResolver`, `ResourceScope`, `EspiQueryOptions` (not yet wired into controllers).
+- **web/api/** - ESPI RESTful API endpoints. GET-only (feed + entry) for ApplicationInformation, Authorization, Customer, CustomerAccount, UsagePoint, MeterReading, ReadingType, IntervalBlock, UsageSummary, ElectricPowerQualitySummary, plus `Batch/Subscription/{id}` (#279: `BatchSubscriptionController` + `SubscriptionFeedAssembler`, one feed of the subscription's usage data; access via `ScopeResolver.canReadSubscription`). `web/api/scope/` holds `ScopeResolver`, `ResourceScope`, `EspiQueryOptions` (`ResourceScope`/`EspiQueryOptions` not yet wired into the per-resource controllers).
- **web/custodian/** - Data custodian admin portal (home, BatchList notification send, settings)
- **web/customer/** - Retail customer portal; most classes here are original legacy code with `@Controller` commented out
- **web/authorize/** - Customer authorization (per-FB consent) screen delegated from the AS
@@ -137,7 +137,7 @@ REST controllers are in `openespi-datacustodian/src/main/java/org/greenbuttonall
Current state (see GitHub epic #119 "CANONICAL BUILD PLAN" for the roadmap):
- All write endpoints (POST/PUT/DELETE) were deliberately removed in #166 and are deferred.
-- Not yet implemented: `Batch/Subscription`, `Batch/Bulk`, `Batch/RetailCustomer`, `Subscription/{id}`, RetailCustomer-scoped URIs, LocalTimeParameters, ReadServiceStatus, and the CustomerAgreement/ServiceSupplier/ServiceLocation/Meter/EndDevice/Statement/ProgramIdMappings endpoints.
+- Not yet implemented: `Batch/Bulk`, `Batch/RetailCustomer`, `Subscription/{id}`, RetailCustomer-scoped URIs, LocalTimeParameters, ReadServiceStatus, and the CustomerAgreement/ServiceSupplier/ServiceLocation/Meter/EndDevice/Statement/ProgramIdMappings endpoints.
- Known defect: Subscription-scoped GETs currently ignore `subscriptionId` and return all records.
- The ten per-resource controllers duplicate find/map/marshal logic; the E1 resource engine (#187, branch `feature/187-e1-resource-engine-usagepoint-triad`, not yet merged) replaces them with one generic controller driven by `EspiResource` + `ResourceFbPolicy` (added in `openespi-common/.../common/scope/` on that branch, alongside the existing `FunctionBlock`).
@@ -358,7 +358,6 @@ Still in progress (logic migration from the original OpenESPI code):
The source of truth for status and roadmap is GitHub epic #119 ("CANONICAL BUILD PLAN") and its sub-issues. The root `PHASE_*.md`, `MULTI_PHASE_SCHEMA_COMPLIANCE_PLAN.md`, `ISSUE_101_*.md`, `openespi-common/Phase_A-Flyway_Migration_Inventory.md`, `openespi-common/PROFILE_MIGRATION_SUMMARY.md`, `openespi-datacustodian/controll-update-status.md`, and `openespi-authserver/MIGRATION_ROADMAP.md` are historical and stale.
Known rule violations / defects to be aware of:
-- `domain/common/DateTimeInterval` carries `@XmlType` despite being an `@Embeddable` (violates the JAXB rule above; collides with `DateTimeIntervalDto`)
- `MeterMapper` ignores meter multipliers (silently dropped on export/import)
- Five orphaned `*_related_links` tables are still created in the vendor V2 scripts
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java
index af7d178b..7f3d2bd5 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/common/DateTimeInterval.java
@@ -27,10 +27,6 @@
import jakarta.persistence.Column;
import jakarta.persistence.Embeddable;
-import jakarta.xml.bind.annotation.XmlAccessType;
-import jakarta.xml.bind.annotation.XmlAccessorType;
-import jakarta.xml.bind.annotation.XmlElement;
-import jakarta.xml.bind.annotation.XmlType;
/**
* Date and time interval with duration.
@@ -41,14 +37,14 @@
*
* Per ESPI 4.0 espi.xsd lines 1337-1357.
*
+ *
JPA only: the XML form is {@code DateTimeIntervalDto} (usage) or {@code CustomerDateTimeIntervalDto}
+ * (customer). The JAXB annotations this class used to carry declared the same XML type as
+ * {@code DateTimeIntervalDto}, which broke the Data Custodian's JAXB context once the DTO was put in the espi
+ * namespace (#279; see CLAUDE.md, JAXB Annotation Guidelines).
+ *
* @see ESPI Specification
*/
@Embeddable
-@XmlAccessorType(XmlAccessType.FIELD)
-@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi", propOrder = {
- "duration",
- "start"
-})
@Getter
@Setter
@NoArgsConstructor
@@ -62,7 +58,6 @@ public class DateTimeInterval {
*
Required field. Type: UInt32 (unsigned 32-bit integer, max 4,294,967,295).
* XSD: espi.xsd line 1344
*/
- @XmlElement(name = "duration", namespace = "http://naesb.org/espi", required = true)
@Column(name = "duration", nullable = false)
private Long duration;
@@ -72,7 +67,6 @@ public class DateTimeInterval {
*
Required field. Type: TimeType (seconds since Unix epoch, Jan 1, 1970 UTC).
* XSD: espi.xsd line 1349
*/
- @XmlElement(name = "start", namespace = "http://naesb.org/espi", required = true)
@Column(name = "start", nullable = false)
private Long start;
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java
index 89fcb2f9..0b009bd0 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/atom/UsageAtomEntryDto.java
@@ -109,7 +109,8 @@ public static class Content {
@XmlElement(name = "ReadingType", type = ReadingTypeDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "ElectricPowerQualitySummary", type = ElectricPowerQualitySummaryDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "UsageSummary", type = UsageSummaryDto.class, namespace = "http://naesb.org/espi"),
- @XmlElement(name = "TimeConfiguration", type = TimeConfigurationDto.class, namespace = "http://naesb.org/espi"),
+ // espi.xsd: (#279)
+ @XmlElement(name = "LocalTimeParameters", type = TimeConfigurationDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "ApplicationInformation", type = ApplicationInformationDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "Authorization", type = AuthorizationDto.class, namespace = "http://naesb.org/espi"),
@XmlElement(name = "Subscription", type = SubscriptionDto.class, namespace = "http://naesb.org/espi"),
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java
index 513da1ca..96f3ef93 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/common/DateTimeIntervalDto.java
@@ -34,11 +34,17 @@
*
* Represents a time interval with start and duration.
* Used in various Green Button resources for time-based data.
+ *
+ * espi.xsd's {@code DateTimeInterval}: {@code espi:duration} then {@code espi:start}, both in the espi namespace
+ * (#279). This package has no {@code @XmlSchema}, so without the explicit namespaces they were written
+ * unqualified, and in the wrong order, failing XSD validation. The customer domain uses
+ * {@code CustomerDateTimeIntervalDto} (cust namespace). The fields stay declared {@code start, duration}, so
+ * the all-args constructor keeps its {@code (start, duration)} order.
*/
-@XmlRootElement(name = "DateTimeInterval")
+@XmlRootElement(name = "DateTimeInterval", namespace = "http://naesb.org/espi")
@XmlAccessorType(XmlAccessType.FIELD)
-@XmlType(name = "DateTimeInterval", propOrder = {
- "start", "duration"
+@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi", propOrder = {
+ "duration", "start"
})
@Getter
@Setter
@@ -46,10 +52,10 @@
@AllArgsConstructor
public class DateTimeIntervalDto {
- @XmlElement(name = "start")
+ @XmlElement(name = "start", namespace = "http://naesb.org/espi")
private Long start;
- @XmlElement(name = "duration")
+ @XmlElement(name = "duration", namespace = "http://naesb.org/espi")
private Long duration;
/**
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java
index 1ed04db7..aa1a666a 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDto.java
@@ -24,7 +24,6 @@
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
-import org.greenbuttonalliance.espi.common.dto.common.DateTimeIntervalDto;
import java.io.Serializable;
import java.time.OffsetDateTime;
@@ -140,7 +139,7 @@ public class CustomerAgreementDto {
* Date and time interval this agreement is valid (from going into effect to termination).
*/
@XmlElement(name = "validityInterval", namespace = "http://naesb.org/espi/customer")
- private DateTimeIntervalDto validityInterval;
+ private CustomerDateTimeIntervalDto validityInterval;
// ==================== CustomerAgreement fields (customer.xsd lines 159-209) ====================
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java
new file mode 100644
index 00000000..98eac49d
--- /dev/null
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerDateTimeIntervalDto.java
@@ -0,0 +1,55 @@
+/*
+ *
+ * Copyright (c) 2025-2026 Green Button Alliance, Inc.
+ *
+ *
+ * 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 org.greenbuttonalliance.espi.common.dto.customer;
+
+import jakarta.xml.bind.annotation.XmlAccessType;
+import jakarta.xml.bind.annotation.XmlAccessorType;
+import jakarta.xml.bind.annotation.XmlElement;
+import jakarta.xml.bind.annotation.XmlType;
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+import lombok.NoArgsConstructor;
+import lombok.Setter;
+
+import java.io.Serializable;
+
+/**
+ * customer.xsd's own {@code DateTimeInterval} (cust namespace): {@code duration} then {@code start}, both
+ * optional. The usage-domain {@code DateTimeIntervalDto} is in the espi namespace, so using it here would put
+ * espi elements inside customer data and declare a second ESPI namespace in customer feeds (#279).
+ *
+ * The all-args constructor takes {@code (start, duration)}, like {@code DateTimeIntervalDto}.
+ */
+@XmlAccessorType(XmlAccessType.FIELD)
+@XmlType(name = "DateTimeInterval", namespace = "http://naesb.org/espi/customer", propOrder = {
+ "duration", "start"
+})
+@Getter
+@Setter
+@NoArgsConstructor
+@AllArgsConstructor
+public class CustomerDateTimeIntervalDto implements Serializable {
+
+ @XmlElement(name = "start", namespace = "http://naesb.org/espi/customer")
+ private Long start;
+
+ @XmlElement(name = "duration", namespace = "http://naesb.org/espi/customer")
+ private Long duration;
+}
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java
index 7aea2726..3a18268b 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDto.java
@@ -36,10 +36,14 @@
* Complies with NAESB ESPI 4.0 XSD specification.
*
* Field order strictly matches espi.xsd TimeConfiguration element sequence.
+ *
+ * The element is {@code espi:LocalTimeParameters}: espi.xsd declares
+ * {@code } and has no global
+ * {@code TimeConfiguration} element, so {@code } fails XSD validation (#279).
*
* @see NAESB ESPI 4.0
*/
-@XmlRootElement(name = "TimeConfiguration", namespace = "http://naesb.org/espi")
+@XmlRootElement(name = "LocalTimeParameters", namespace = "http://naesb.org/espi")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType(name = "TimeConfiguration", namespace = "http://naesb.org/espi", propOrder = {
"dstEndRule",
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java
index f6609997..6e8dc980 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/usage/TariffRiderRefMapper.java
@@ -94,11 +94,13 @@ default List tariffRiderRefsDtoToEntityList(TariffRiderRef
* Wraps the list in the TariffRiderRefsDto container.
*
* @param entities the list of tariff rider ref entities
- * @return the wrapper DTO containing tariff rider refs, or null if input is null
+ * @return the wrapper DTO containing tariff rider refs, or null if there are none: espi.xsd's
+ * {@code TariffRiderRefs} needs at least one {@code tariffRiderRef}, so an empty wrapper is
+ * invalid, while the element itself is optional (#279)
*/
@Named("entityListToTariffRiderRefsDto")
default TariffRiderRefsDto entityListToTariffRiderRefsDto(List entities) {
- if (entities == null) {
+ if (entities == null || entities.isEmpty()) {
return null;
}
return new TariffRiderRefsDto(toDtoList(entities));
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java
index c0d4d684..f26e2d0f 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/service/BaseExportService.java
@@ -255,35 +255,74 @@ public void exportFeed(String feedHref, String titl
public AtomFeedDto buildFeed(String feedHref, String title, List entities,
Function super E, ?> toContent) {
Objects.requireNonNull(feedHref, "feedHref");
- OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC).truncatedTo(ChronoUnit.SECONDS);
-
- List entries = new ArrayList<>(entities.size());
+ List entries = new ArrayList<>(entities.size());
String resource = null;
for (E entity : entities) {
Object content = toContent.apply(entity);
- String entryResource = resourceName(content);
- resource = resource == null ? entryResource : resource;
+ resource = resource == null ? resourceName(content) : resource;
+ entries.add(new FeedEntry(entity, content,
+ href(entity.getSelfLink(), feedHref + "/" + entity.getId()),
+ href(entity.getUpLink(), feedHref), List.of()));
+ }
+ // An empty feed has no entry to name its resource, so the href's last segment is used (#197).
+ return buildFeedOf(feedHref, resource != null ? resource : lastPathSegment(feedHref), title, entries);
+ }
+
+ /**
+ * One entry of a feed that may mix resource types (e.g. {@code Batch/Subscription}, #279): the
+ * resource, the DTO carried in its {@code }, its {@code self} and {@code up} hrefs, and
+ * any {@code related} links (with their {@code espi-feed/...} or {@code espi-entry/...} types).
+ */
+ public record FeedEntry(IdentifiedObject entity, Object content, String selfHref, String upHref,
+ List related) {
+
+ public FeedEntry {
+ Objects.requireNonNull(entity, "entity");
+ Objects.requireNonNull(content, "content");
+ Objects.requireNonNull(selfHref, "selfHref");
+ Objects.requireNonNull(upHref, "upHref");
+ related = related == null ? List.of() : List.copyOf(related);
+ }
+ }
+
+ /**
+ * Builds an Atom feed from prepared entries, which may be of different resource types, in the order
+ * given. Entries are written as described for {@link #buildFeed(String, String, List, Function)}, with
+ * the given hrefs, and each entry's {@code related} links after {@code self} and {@code up}.
+ *
+ * @param feedHref absolute URL of the feed (its self link, and the source of its UUID v5 id)
+ * @param feedResource the resource named in the feed's self link type ({@code espi-feed/}),
+ * given explicitly so an empty feed is typed correctly whatever its href ends in
+ * @param title feed title
+ * @param feedEntries the entries, in feed order; may be empty
+ */
+ public AtomFeedDto buildFeedOf(String feedHref, String feedResource, String title, List feedEntries) {
+ Objects.requireNonNull(feedHref, "feedHref");
+ Objects.requireNonNull(feedResource, "feedResource");
+ OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC).truncatedTo(ChronoUnit.SECONDS);
- String selfHref = href(entity.getSelfLink(), feedHref + "/" + entity.getId());
- String upHref = href(entity.getUpLink(), feedHref);
- List links = List.of(
- new LinkDto("self", selfHref, "espi-entry/" + entryResource),
- new LinkDto("up", upHref, "espi-feed/" + entryResource));
+ List entries = new ArrayList<>(feedEntries.size());
+ for (FeedEntry feedEntry : feedEntries) {
+ IdentifiedObject entity = feedEntry.entity();
+ String entryResource = resourceName(feedEntry.content());
+ List links = new ArrayList<>(2 + feedEntry.related().size());
+ links.add(new LinkDto("self", feedEntry.selfHref(), "espi-entry/" + entryResource));
+ links.add(new LinkDto("up", feedEntry.upHref(), "espi-feed/" + entryResource));
+ links.addAll(feedEntry.related());
String entryTitle = entity.getDescription() != null && !entity.getDescription().isBlank()
? entity.getDescription() : entryResource;
entries.add(newEntry("urn:uuid:" + entity.getId(), entryTitle,
utc(entity.getPublished(), entity.getCreated(), now),
utc(entity.getUpdated(), entity.getCreated(), now),
- links, content));
+ List.copyOf(links), feedEntry.content()));
}
AtomFeedDto feed = new AtomFeedDto();
feed.setId("urn:uuid:" + ID_GENERATOR.generateEspiId(feedHref));
feed.setTitle(title);
feed.setUpdated(now);
- // atom.xsd requires a type on every link: an empty feed takes the resource from its href (#197).
- feed.setLinks(List.of(new LinkDto("self", feedHref,
- "espi-feed/" + (resource != null ? resource : lastPathSegment(feedHref)))));
+ // atom.xsd requires a type on every link.
+ feed.setLinks(List.of(new LinkDto("self", feedHref, "espi-feed/" + feedResource)));
feed.setEntries(entries);
return feed;
}
diff --git a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java
index 3275893e..e4b08afc 100644
--- a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java
+++ b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/customer/CustomerAgreementDtoTest.java
@@ -21,7 +21,7 @@
import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
import org.greenbuttonalliance.espi.common.dto.atom.CustomerAtomEntryDto;
-import org.greenbuttonalliance.espi.common.dto.common.DateTimeIntervalDto;
+import org.greenbuttonalliance.espi.common.dto.customer.CustomerDateTimeIntervalDto;
import org.greenbuttonalliance.espi.common.service.impl.DtoExportServiceImpl;
import org.greenbuttonalliance.espi.common.dto.customer.ElectronicAddressDto;
import org.junit.jupiter.api.BeforeEach;
@@ -250,7 +250,7 @@ void shouldExportElectronicAddressWithAllFields() {
"Title",
null, null, null,
now,
- new DateTimeIntervalDto(now.toEpochSecond(), 3600L),
+ new CustomerDateTimeIntervalDto(now.toEpochSecond(), 3600L),
"LOAD_MGMT",
false,
null,
@@ -314,7 +314,7 @@ private CustomerAgreementDto createFullCustomerAgreementDto() {
);
OffsetDateTime validityStart = OffsetDateTime.of(2025, 1, 1, 0, 0, 0, 0, ZoneOffset.UTC);
- DateTimeIntervalDto validityInterval = new DateTimeIntervalDto(
+ CustomerDateTimeIntervalDto validityInterval = new CustomerDateTimeIntervalDto(
validityStart.toEpochSecond(),
31536000L // 1 year in seconds
);
diff --git a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java
index 2781b968..735767ea 100644
--- a/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java
+++ b/openespi-common/src/test/java/org/greenbuttonalliance/espi/common/dto/usage/TimeConfigurationDtoTest.java
@@ -72,13 +72,12 @@ void shouldMarshalTimeConfigurationWithRealisticData() throws Exception {
String xml = writer.toString();
// Verify XML structure
- assertThat(xml).contains("TimeConfiguration");
- assertThat(xml).contains("http://naesb.org/espi");
+ // espi.xsd's element for a TimeConfiguration is LocalTimeParameters (#279).
// Note: mRID/uuid is handled by Atom wrapper, not the ESPI resource itself
- assertThat(xml).contains("tzOffset"); // Element should be present
- assertThat(xml).contains("-28800"); // Timezone value
- assertThat(xml).contains("dstOffset");
- assertThat(xml).contains("3600");
+ assertThat(xml)
+ .contains(" fb4 =
- AuthorityAuthorizationManager.hasAuthority("FB_4");
+ AuthorityAuthorizationManager.hasAuthority(UsageFunctionBlockAuthorities.INTERVAL_METERING);
AuthorizationManager commodity =
AuthorityAuthorizationManager.hasAnyAuthority(commodityAuthorities());
AuthorizationManager usageData =
@@ -125,10 +123,11 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http,
// Usage summaries (data-shape FBs) and power-quality summary (FB_17).
AuthorizationManager usageSummary =
- AuthorizationManagers.anyOf(admin,
- AuthorityAuthorizationManager.hasAnyAuthority("FB_15", "FB_16", "FB_27", "FB_28"));
+ AuthorizationManagers.anyOf(admin, AuthorityAuthorizationManager.hasAnyAuthority(
+ UsageFunctionBlockAuthorities.USAGE_SUMMARY.toArray(String[]::new)));
AuthorizationManager powerQuality =
- AuthorizationManagers.anyOf(admin, AuthorityAuthorizationManager.hasAuthority("FB_17"));
+ AuthorizationManagers.anyOf(admin, AuthorityAuthorizationManager.hasAnyAuthority(
+ UsageFunctionBlockAuthorities.POWER_QUALITY.toArray(String[]::new)));
// Customer / PII resources — least-privilege per the ESPI Customer-PII catalog: the base
// Connect-My-Data customer FB (FB_53) AND the resource-specific FB, or admin. FB→resource
@@ -290,10 +289,7 @@ public OpaqueTokenIntrospector introspector() {
* drifts from the spec.
*/
private static String[] commodityAuthorities() {
- return Stream.of(FunctionBlock.values())
- .filter(fb -> fb.getCategory() == FunctionBlockCategory.COMMODITY)
- .map(fb -> "FB_" + fb.getId())
- .toArray(String[]::new);
+ return UsageFunctionBlockAuthorities.COMMODITY.toArray(String[]::new);
}
/**
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
new file mode 100644
index 00000000..2e594802
--- /dev/null
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
@@ -0,0 +1,68 @@
+/*
+ *
+ * Copyright (c) 2025-2026 Green Button Alliance, Inc.
+ *
+ *
+ * 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 org.greenbuttonalliance.espi.datacustodian.config;
+
+import org.greenbuttonalliance.espi.common.scope.FunctionBlock;
+import org.greenbuttonalliance.espi.common.scope.FunctionBlockCategory;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.GrantedAuthority;
+
+import java.util.List;
+import java.util.stream.Stream;
+
+/**
+ * The Function Block authorities ({@code FB_}, from {@link EspiScopeOpaqueTokenIntrospector}) that grant
+ * each kind of usage data. {@link SecurityConfiguration}'s URL rules and the {@code Batch/Subscription} feed
+ * (#279), which holds several resource types behind one URL, both read them here, so a rule is stated once
+ * until #187's {@code ResourceFbPolicy} replaces them.
+ */
+public final class UsageFunctionBlockAuthorities {
+
+ /** Interval metering: the base for UsagePoint, MeterReading, ReadingType, IntervalBlock, LocalTimeParameters. */
+ public static final String INTERVAL_METERING = "FB_4";
+
+ /** Usage summaries (the data-shape FBs). */
+ public static final List USAGE_SUMMARY = List.of("FB_15", "FB_16", "FB_27", "FB_28");
+
+ /** Power-quality summary. */
+ public static final List POWER_QUALITY = List.of("FB_17");
+
+ /** Every commodity FB (electricity, gas, water, ...): at least one is needed with {@link #INTERVAL_METERING}. */
+ public static final List COMMODITY = Stream.of(FunctionBlock.values())
+ .filter(fb -> fb.getCategory() == FunctionBlockCategory.COMMODITY)
+ .map(fb -> "FB_" + fb.getId())
+ .toList();
+
+ private UsageFunctionBlockAuthorities() {
+ }
+
+ /** Whether the authentication holds at least one of the authorities. */
+ public static boolean hasAny(Authentication authentication, List authorities) {
+ if (authentication == null) {
+ return false;
+ }
+ for (GrantedAuthority granted : authentication.getAuthorities()) {
+ if (authorities.contains(granted.getAuthority())) {
+ return true;
+ }
+ }
+ return false;
+ }
+}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
new file mode 100644
index 00000000..4bb17df6
--- /dev/null
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -0,0 +1,121 @@
+/*
+ *
+ * Copyright (c) 2025-2026 Green Button Alliance, Inc.
+ *
+ *
+ * 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 org.greenbuttonalliance.espi.datacustodian.web.api;
+
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.annotations.responses.ApiResponse;
+import io.swagger.v3.oas.annotations.security.SecurityRequirement;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
+import org.greenbuttonalliance.espi.common.scope.EspiScope;
+import org.greenbuttonalliance.espi.common.service.impl.UsageExportService;
+import org.greenbuttonalliance.espi.datacustodian.config.UsageFunctionBlockAuthorities;
+import org.greenbuttonalliance.espi.datacustodian.web.api.SubscriptionFeedAssembler.Grants;
+import org.greenbuttonalliance.espi.datacustodian.web.api.scope.ScopeResolver;
+import org.springframework.http.HttpStatus;
+import org.springframework.http.MediaType;
+import org.springframework.http.ResponseEntity;
+import org.springframework.security.core.Authentication;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
+
+import java.io.ByteArrayOutputStream;
+import java.util.UUID;
+
+/**
+ * {@code GET /espi/1_1/resource/Batch/Subscription/{subscriptionId}}: the {@code resourceURI} of a customer
+ * access token (REQ.21 6.1.2), answered with one Atom feed of the subscription's energy usage data (#279).
+ *
+ * Access ({@link ScopeResolver#canReadSubscription}): the DataCustodian admin, or a customer access
+ * token for exactly this subscription. Anything else gets 403, whether or not the subscription exists. The
+ * URL rule in {@code SecurityConfiguration} requires interval metering and a commodity Function Block first,
+ * and the token's Function Blocks decide which summaries the feed holds
+ * ({@link UsageFunctionBlockAuthorities}).
+ */
+@RestController
+@RequestMapping("/espi/1_1/resource")
+@Tag(name = "Batch", description = "ESPI Batch resource endpoints")
+@SecurityRequirement(name = "oauth2")
+public class BatchSubscriptionController {
+
+ private static final String BATCH_SUBSCRIPTION = "/Batch/Subscription/";
+
+ private final ScopeResolver scopeResolver;
+ private final SubscriptionFeedAssembler assembler;
+ private final UsageExportService usageExportService;
+
+ public BatchSubscriptionController(ScopeResolver scopeResolver, SubscriptionFeedAssembler assembler,
+ UsageExportService usageExportService) {
+ this.scopeResolver = scopeResolver;
+ this.assembler = assembler;
+ this.usageExportService = usageExportService;
+ }
+
+ // No "produces": WebConfiguration's default content type is JSON when a request has no Accept header, so
+ // an XML-only mapping would answer such requests 406. The response is always application/atom+xml.
+ @GetMapping("/Batch/Subscription/{subscriptionId}")
+ @Operation(
+ summary = "Get a Subscription's energy usage data",
+ description = "One Atom feed with the subscription's UsagePoints and their MeterReadings, ReadingTypes,"
+ + " IntervalBlocks, summaries and LocalTimeParameters, as granted by the token's scope",
+ responses = {
+ @ApiResponse(responseCode = "200", description = "The subscription's feed"),
+ @ApiResponse(responseCode = "401", description = "Unauthorized"),
+ @ApiResponse(responseCode = "403", description = "Not this token's subscription"),
+ @ApiResponse(responseCode = "404", description = "No such subscription (DataCustodian admin only)")
+ }
+ )
+ public ResponseEntity getSubscription(
+ @Parameter(description = "The subscription id from the token's resourceURI", required = true)
+ @PathVariable UUID subscriptionId,
+ Authentication authentication) {
+
+ if (!scopeResolver.canReadSubscription(authentication, subscriptionId)) {
+ throw new ResponseStatusException(HttpStatus.FORBIDDEN);
+ }
+ String feedHref = ServletUriComponentsBuilder.fromCurrentRequestUri().toUriString();
+ String resourceBase = feedHref.substring(0, feedHref.indexOf(BATCH_SUBSCRIPTION));
+ AtomFeedDto feed = assembler.build(subscriptionId, resourceBase, feedHref, grants(authentication))
+ .orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
+
+ ByteArrayOutputStream out = new ByteArrayOutputStream();
+ usageExportService.exportDto(feed, out);
+ return ResponseEntity.ok()
+ .contentType(MediaType.APPLICATION_ATOM_XML)
+ .body(out.toByteArray());
+ }
+
+ /** The admin sees everything; a customer token sees what its Function Blocks and HistoryLength grant. */
+ private Grants grants(Authentication authentication) {
+ if (scopeResolver.isAdmin(authentication)) {
+ return Grants.all();
+ }
+ Integer historyLength = scopeResolver.espiScope(authentication).map(EspiScope::historyLength).orElse(null);
+ return new Grants(
+ UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.USAGE_SUMMARY),
+ UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.POWER_QUALITY),
+ historyLength == null ? null : historyLength.longValue());
+ }
+}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
new file mode 100644
index 00000000..305f2b0d
--- /dev/null
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -0,0 +1,233 @@
+/*
+ *
+ * Copyright (c) 2025-2026 Green Button Alliance, Inc.
+ *
+ *
+ * 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 org.greenbuttonalliance.espi.datacustodian.web.api;
+
+import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
+import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.MeterReadingEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.ReadingTypeEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.SubscriptionEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.TimeConfigurationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsagePointEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsageSummaryEntity;
+import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
+import org.greenbuttonalliance.espi.common.dto.atom.LinkDto;
+import org.greenbuttonalliance.espi.common.mapper.usage.ElectricPowerQualitySummaryMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.IntervalBlockMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.MeterReadingMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.ReadingTypeMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.TimeConfigurationMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.UsagePointMapper;
+import org.greenbuttonalliance.espi.common.mapper.usage.UsageSummaryMapper;
+import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.service.BaseExportService.FeedEntry;
+import org.greenbuttonalliance.espi.common.service.impl.UsageExportService;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Clock;
+import java.util.ArrayList;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.Set;
+import java.util.UUID;
+
+/**
+ * Builds {@code Batch/Subscription/{subscriptionId}} (#279): one Atom feed with the energy usage data of a
+ * subscription. The caller has already checked who may read it ({@code ScopeResolver#canReadSubscription}).
+ *
+ * Entries, in the order of certified feeds, for each UsagePoint the customer selected:
+ *
+ * - the UsagePoint;
+ * - each MeterReading, its ReadingType (once in the feed, even if shared) and its IntervalBlocks;
+ * - the UsageSummaries and ElectricPowerQualitySummaries, when the token's Function Blocks grant them;
+ * - its LocalTimeParameters.
+ *
+ *
+ * Hrefs are subscription-scoped ({@code .../Subscription/{id}/UsagePoint/{id}/...}); ReadingType and
+ * LocalTimeParameters are root resources. Each entry has {@code self} and {@code up}, plus {@code related}
+ * links to the resources it refers to that are in the feed.
+ *
+ * {@code HistoryLength} (REQ.21: "the amount of historical information available from the Data
+ * Custodian in seconds") drops IntervalBlocks that ended before now minus that length. {@code BlockDuration}
+ * describes the blocks and selects nothing.
+ */
+@Component
+public class SubscriptionFeedAssembler {
+
+ /** What the token grants, beyond reading the subscription at all. */
+ public record Grants(boolean usageSummaries, boolean powerQualitySummaries, Long historyLengthSeconds) {
+
+ public static Grants all() {
+ return new Grants(true, true, null);
+ }
+ }
+
+ private final SubscriptionRepository subscriptionRepository;
+ private final UsageExportService usageExportService;
+ private final UsagePointMapper usagePointMapper;
+ private final MeterReadingMapper meterReadingMapper;
+ private final ReadingTypeMapper readingTypeMapper;
+ private final IntervalBlockMapper intervalBlockMapper;
+ private final UsageSummaryMapper usageSummaryMapper;
+ private final ElectricPowerQualitySummaryMapper powerQualitySummaryMapper;
+ private final TimeConfigurationMapper timeConfigurationMapper;
+ private Clock clock = Clock.systemUTC();
+
+ public SubscriptionFeedAssembler(SubscriptionRepository subscriptionRepository,
+ UsageExportService usageExportService,
+ UsagePointMapper usagePointMapper,
+ MeterReadingMapper meterReadingMapper,
+ ReadingTypeMapper readingTypeMapper,
+ IntervalBlockMapper intervalBlockMapper,
+ UsageSummaryMapper usageSummaryMapper,
+ ElectricPowerQualitySummaryMapper powerQualitySummaryMapper,
+ TimeConfigurationMapper timeConfigurationMapper) {
+ this.subscriptionRepository = subscriptionRepository;
+ this.usageExportService = usageExportService;
+ this.usagePointMapper = usagePointMapper;
+ this.meterReadingMapper = meterReadingMapper;
+ this.readingTypeMapper = readingTypeMapper;
+ this.intervalBlockMapper = intervalBlockMapper;
+ this.usageSummaryMapper = usageSummaryMapper;
+ this.powerQualitySummaryMapper = powerQualitySummaryMapper;
+ this.timeConfigurationMapper = timeConfigurationMapper;
+ }
+
+ /** For tests: the clock {@code HistoryLength} is measured from. */
+ void setClock(Clock clock) {
+ this.clock = clock;
+ }
+
+ /**
+ * The subscription's feed, or empty if there is no such subscription.
+ *
+ * @param resourceBase the DC's resource base, {@code https://{host}/.../espi/1_1/resource}
+ * @param feedHref the request's absolute URL (the feed's self link)
+ */
+ @Transactional(readOnly = true)
+ public Optional build(UUID subscriptionId, String resourceBase, String feedHref, Grants grants) {
+ return subscriptionRepository.findById(subscriptionId)
+ .map(subscription -> usageExportService.buildFeedOf(feedHref, "Subscription",
+ "Green Button Subscription Feed", entries(subscription, resourceBase, grants)));
+ }
+
+ private List entries(SubscriptionEntity subscription, String resourceBase, Grants grants) {
+ String subscriptionHref = resourceBase + "/Subscription/" + subscription.getId();
+ Long earliestEnd = grants.historyLengthSeconds() == null ? null
+ : clock.instant().getEpochSecond() - grants.historyLengthSeconds();
+ Set readingTypesInFeed = new HashSet<>();
+ List entries = new ArrayList<>();
+
+ for (UsagePointEntity usagePoint : subscription.getUsagePoints()) {
+ String usagePointFeed = subscriptionHref + "/UsagePoint";
+ String usagePointHref = usagePointFeed + "/" + usagePoint.getId();
+ List summaries = grants.usageSummaries() ? usagePoint.getUsageSummaries() : List.of();
+ List qualitySummaries =
+ grants.powerQualitySummaries() ? usagePoint.getElectricPowerQualitySummaries() : List.of();
+ TimeConfigurationEntity localTime = usagePoint.getLocalTimeParameters();
+
+ List usagePointRelated = new ArrayList<>();
+ if (!usagePoint.getMeterReadings().isEmpty()) {
+ usagePointRelated.add(related(usagePointHref + "/MeterReading", "espi-feed/MeterReading"));
+ }
+ if (!summaries.isEmpty()) {
+ usagePointRelated.add(related(usagePointHref + "/UsageSummary", "espi-feed/UsageSummary"));
+ }
+ if (!qualitySummaries.isEmpty()) {
+ usagePointRelated.add(related(usagePointHref + "/ElectricPowerQualitySummary",
+ "espi-feed/ElectricPowerQualitySummary"));
+ }
+ if (localTime != null) {
+ usagePointRelated.add(related(resourceBase + "/LocalTimeParameters/" + localTime.getId(),
+ "espi-entry/LocalTimeParameters"));
+ }
+ entries.add(new FeedEntry(usagePoint, usagePointMapper.toDto(usagePoint), usagePointHref,
+ usagePointFeed, usagePointRelated));
+
+ for (MeterReadingEntity meterReading : usagePoint.getMeterReadings()) {
+ addMeterReading(entries, meterReading, usagePointHref, resourceBase, earliestEnd, readingTypesInFeed);
+ }
+ for (UsageSummaryEntity summary : summaries) {
+ String feed = usagePointHref + "/UsageSummary";
+ entries.add(new FeedEntry(summary, usageSummaryMapper.toDto(summary), feed + "/" + summary.getId(),
+ feed, List.of()));
+ }
+ for (ElectricPowerQualitySummaryEntity summary : qualitySummaries) {
+ String feed = usagePointHref + "/ElectricPowerQualitySummary";
+ entries.add(new FeedEntry(summary, powerQualitySummaryMapper.toDto(summary),
+ feed + "/" + summary.getId(), feed, List.of()));
+ }
+ if (localTime != null) {
+ String feed = resourceBase + "/LocalTimeParameters";
+ entries.add(new FeedEntry(localTime, timeConfigurationMapper.toDto(localTime),
+ feed + "/" + localTime.getId(), feed, List.of()));
+ }
+ }
+ return entries;
+ }
+
+ private void addMeterReading(List entries, MeterReadingEntity meterReading, String usagePointHref,
+ String resourceBase, Long earliestEnd, Set readingTypesInFeed) {
+ String meterReadingFeed = usagePointHref + "/MeterReading";
+ String meterReadingHref = meterReadingFeed + "/" + meterReading.getId();
+ ReadingTypeEntity readingType = meterReading.getReadingType();
+ List blocks = meterReading.getIntervalBlocks().stream()
+ .filter(block -> withinHistory(block, earliestEnd))
+ .toList();
+
+ List meterReadingRelated = new ArrayList<>();
+ if (readingType != null) {
+ meterReadingRelated.add(related(resourceBase + "/ReadingType/" + readingType.getId(), "espi-entry/ReadingType"));
+ }
+ if (!blocks.isEmpty()) {
+ meterReadingRelated.add(related(meterReadingHref + "/IntervalBlock", "espi-feed/IntervalBlock"));
+ }
+ entries.add(new FeedEntry(meterReading, meterReadingMapper.toDto(meterReading), meterReadingHref,
+ meterReadingFeed, meterReadingRelated));
+
+ if (readingType != null && readingTypesInFeed.add(readingType.getId())) {
+ String feed = resourceBase + "/ReadingType";
+ entries.add(new FeedEntry(readingType, readingTypeMapper.toDto(readingType),
+ feed + "/" + readingType.getId(), feed, List.of()));
+ }
+ for (IntervalBlockEntity block : blocks) {
+ String feed = meterReadingHref + "/IntervalBlock";
+ entries.add(new FeedEntry(block, intervalBlockMapper.toDto(block), feed + "/" + block.getId(), feed,
+ List.of()));
+ }
+ }
+
+ /** A block without an interval is kept: there is nothing to measure it against. */
+ private static boolean withinHistory(IntervalBlockEntity block, Long earliestEnd) {
+ DateTimeInterval interval = block.getInterval();
+ if (earliestEnd == null || interval == null || interval.getStart() == null) {
+ return true;
+ }
+ long end = interval.getStart() + (interval.getDuration() == null ? 0 : interval.getDuration());
+ return end > earliestEnd;
+ }
+
+ private static LinkDto related(String href, String type) {
+ return new LinkDto("related", href, type);
+ }
+}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
index 6862fca5..12e3c1d2 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
@@ -19,13 +19,18 @@
package org.greenbuttonalliance.espi.datacustodian.web.api.scope;
import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.scope.EspiScope;
import org.greenbuttonalliance.espi.common.uri.EspiBatchUri;
+import org.greenbuttonalliance.espi.datacustodian.config.EspiScopeOpaqueTokenIntrospector;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal;
import org.springframework.stereotype.Component;
+import java.util.Collection;
import java.util.LinkedHashSet;
+import java.util.List;
+import java.util.Optional;
import java.util.Set;
import java.util.UUID;
@@ -110,6 +115,70 @@ public ResourceScope resolve(Authentication authentication) {
return ResourceScope.of(usagePointIds, retailCustomerIds);
}
+ /**
+ * Whether the caller may read {@code Batch/Subscription/{subscriptionId}} (#279): the DataCustodian
+ * admin, or a customer access token whose introspected {@code resourceURI} names exactly this
+ * subscription. A Third Party's client access token ({@code FB=34_35}) never may, whatever its URIs: it
+ * is for Authorization and Bulk. Unknown and foreign subscriptions are answered alike, so the caller
+ * learns nothing about subscriptions it does not hold.
+ */
+ public boolean canReadSubscription(Authentication authentication, UUID subscriptionId) {
+ if (subscriptionId == null || authentication == null || !authentication.isAuthenticated()) {
+ return false;
+ }
+ if (hasAdminAuthority(authentication)) {
+ return true;
+ }
+ if (hasAuthority(authentication, EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN)
+ || !(authentication.getPrincipal() instanceof OAuth2AuthenticatedPrincipal principal)) {
+ return false;
+ }
+ String resourceUri = stringAttribute(principal, "resourceURI");
+ return resourceUri != null && EspiBatchUri.subscriptionId(resourceUri)
+ .flatMap(ScopeResolver::parseUuid)
+ .filter(subscriptionId::equals)
+ .isPresent();
+ }
+
+ /**
+ * The token's ESPI scope (the {@code FB=...} scope string, with its {@code HistoryLength} and other
+ * terms), or empty for the admin, a token without one, or a scope that does not parse.
+ */
+ public Optional espiScope(Authentication authentication) {
+ if (authentication == null || !(authentication.getPrincipal() instanceof OAuth2AuthenticatedPrincipal principal)) {
+ return Optional.empty();
+ }
+ Object scope = principal.getAttribute("scope");
+ Collection> scopes = scope instanceof Collection> collection ? collection
+ : scope instanceof String s ? List.of(s.trim().split("\\s+")) : List.of();
+ for (Object value : scopes) {
+ String text = value == null ? "" : value.toString().trim();
+ if (text.regionMatches(true, 0, "FB=", 0, 3)
+ && !EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN_SCOPE.equals(text)) {
+ try {
+ return Optional.of(EspiScope.parse(text));
+ } catch (IllegalArgumentException ex) {
+ return Optional.empty();
+ }
+ }
+ }
+ return Optional.empty();
+ }
+
+ /** Whether the caller holds the DataCustodian admin authority. */
+ public boolean isAdmin(Authentication authentication) {
+ return authentication != null && hasAdminAuthority(authentication);
+ }
+
+ private static boolean hasAuthority(Authentication authentication, String name) {
+ for (GrantedAuthority authority : authentication.getAuthorities()) {
+ if (name.equals(authority.getAuthority())) {
+ return true;
+ }
+ }
+ return false;
+ }
+
private boolean hasAdminAuthority(Authentication authentication) {
for (GrantedAuthority authority : authentication.getAuthorities()) {
if (ADMIN_AUTHORITY.equals(authority.getAuthority())) {
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
new file mode 100644
index 00000000..376877d9
--- /dev/null
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -0,0 +1,367 @@
+/*
+ *
+ * Copyright (c) 2025-2026 Green Button Alliance, Inc.
+ *
+ *
+ * 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 org.greenbuttonalliance.espi.datacustodian.web.api;
+
+import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
+import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
+import org.greenbuttonalliance.espi.common.domain.common.enums.GrantType;
+import org.greenbuttonalliance.espi.common.domain.usage.ApplicationInformationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.AuthorizationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.RetailCustomerEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.IntervalReadingEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.MeterReadingEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.ReadingTypeEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.SubscriptionEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.TimeConfigurationEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsagePointEntity;
+import org.greenbuttonalliance.espi.common.domain.usage.UsageSummaryEntity;
+import org.greenbuttonalliance.espi.common.repositories.usage.ApplicationInformationRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.AuthorizationRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.RetailCustomerRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.repositories.usage.UsagePointRepository;
+import org.greenbuttonalliance.espi.common.xml.EspiXmlSchemaValidator;
+import org.greenbuttonalliance.espi.datacustodian.config.EspiScopeOpaqueTokenIntrospector;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.webmvc.test.autoconfigure.AutoConfigureMockMvc;
+import org.springframework.security.core.GrantedAuthority;
+import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.test.context.ActiveProfiles;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.request.RequestPostProcessor;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.Instant;
+import java.util.Arrays;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Set;
+import java.util.UUID;
+import java.util.regex.Pattern;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.springframework.security.test.web.servlet.request.SecurityMockMvcRequestPostProcessors.opaqueToken;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * {@code GET /Batch/Subscription/{id}} (#279) with real data, the real export service and the real security
+ * rules: exactly the token's subscription, its Function Blocks and HistoryLength, and an XSD-valid feed.
+ */
+@SpringBootTest
+@AutoConfigureMockMvc
+@ActiveProfiles("test")
+@Transactional
+@DisplayName("Batch/Subscription feed (#279)")
+class BatchSubscriptionIntegrationTest {
+
+ private static final String BASE = "http://localhost/espi/1_1/resource";
+ private static final long DAY = 86_400L;
+ /** Interval metering + interval electricity metering: the URL rule's minimum for Batch. */
+ private static final String[] ENERGY_FBS = {"FB_4", "FB_5"};
+
+ private static final UUID SUBSCRIPTION_A = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a01");
+ private static final UUID SUBSCRIPTION_B = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a02");
+ private static final UUID EMPTY_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a03");
+ private static final UUID USAGE_POINT_A = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f501");
+ private static final UUID USAGE_POINT_B = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f502");
+ private static final UUID METER_READING_A = UUID.fromString("41a6bd77-3d03-59c4-9ab2-65f2cb09b101");
+ private static final UUID READING_TYPE_A = UUID.fromString("6a4ad1c1-8f0b-5d55-a0a0-2d1c3e4f5a01");
+ private static final UUID RECENT_BLOCK = UUID.fromString("7b5be2d2-9a1c-5e66-b1b1-3e2d4f5a6b01");
+ private static final UUID OLD_BLOCK = UUID.fromString("7b5be2d2-9a1c-5e66-b1b1-3e2d4f5a6b02");
+ private static final UUID USAGE_SUMMARY_A = UUID.fromString("8c6cf3e3-ab2d-5f77-82c2-4f3e5a6b7c01");
+ private static final UUID QUALITY_SUMMARY_A = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d01");
+ private static final UUID LOCAL_TIME_A = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e01");
+
+ @Autowired
+ private MockMvc mockMvc;
+
+ @Autowired
+ private AuthorizationRepository authorizationRepository;
+
+ @Autowired
+ private RetailCustomerRepository retailCustomerRepository;
+
+ @Autowired
+ private ApplicationInformationRepository applicationInformationRepository;
+
+ @Autowired
+ private SubscriptionRepository subscriptionRepository;
+
+ @Autowired
+ private UsagePointRepository usagePointRepository;
+
+ @BeforeEach
+ void setUp() {
+ long now = Instant.now().getEpochSecond();
+ UsagePointEntity usagePointA = usagePointRepository.save(usagePointA(now));
+ UsagePointEntity usagePointB = new UsagePointEntity();
+ usagePointB.setId(USAGE_POINT_B);
+ usagePointB.setDescription("Another customer's meter");
+ usagePointB.setServiceCategory(ServiceCategory.ELECTRICITY);
+ usagePointB = usagePointRepository.save(usagePointB);
+
+ subscriptionRepository.save(subscription(SUBSCRIPTION_A, List.of(usagePointA)));
+ subscriptionRepository.save(subscription(SUBSCRIPTION_B, List.of(usagePointB)));
+ subscriptionRepository.saveAndFlush(subscription(EMPTY_SUBSCRIPTION, List.of()));
+ }
+
+ @Test
+ @DisplayName("a customer token gets exactly its subscription's resources, in certified order, as valid ESPI XML")
+ void customer_token_gets_its_subscription() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"));
+ String subscription = BASE + "/Subscription/" + SUBSCRIPTION_A;
+ String usagePoint = subscription + "/UsagePoint/" + USAGE_POINT_A;
+ String meterReading = usagePoint + "/MeterReading/" + METER_READING_A;
+
+ assertThat(xml)
+ .contains("rel=\"self\" href=\"" + BASE + "/Batch/Subscription/" + SUBSCRIPTION_A
+ + "\" type=\"espi-feed/Subscription\"")
+ .contains("href=\"" + usagePoint + "\" type=\"espi-entry/UsagePoint\"",
+ "rel=\"up\" href=\"" + subscription + "/UsagePoint\" type=\"espi-feed/UsagePoint\"",
+ "rel=\"related\" href=\"" + usagePoint + "/MeterReading\" type=\"espi-feed/MeterReading\"",
+ "rel=\"related\" href=\"" + BASE + "/LocalTimeParameters/" + LOCAL_TIME_A
+ + "\" type=\"espi-entry/LocalTimeParameters\"")
+ .contains("href=\"" + meterReading + "\" type=\"espi-entry/MeterReading\"",
+ "rel=\"related\" href=\"" + BASE + "/ReadingType/" + READING_TYPE_A
+ + "\" type=\"espi-entry/ReadingType\"",
+ "href=\"" + meterReading + "/IntervalBlock/" + RECENT_BLOCK + "\" type=\"espi-entry/IntervalBlock\"",
+ "href=\"" + usagePoint + "/UsageSummary/" + USAGE_SUMMARY_A + "\"",
+ "href=\"" + usagePoint + "/ElectricPowerQualitySummary/" + QUALITY_SUMMARY_A + "\"",
+ "")
+ .doesNotContain(USAGE_POINT_B.toString(), "", "xsi:type");
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
+ "IntervalBlock", "IntervalBlock", "UsageSummary", "ElectricPowerQualitySummary", "LocalTimeParameters");
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("without FB_16 and FB_17 there are no summaries, and no related links to them")
+ void summaries_need_their_function_blocks() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5"));
+
+ assertThat(xml)
+ .doesNotContain(" attributes.put("resourceURI", BASE + "/Batch/Subscription/" + SUBSCRIPTION_A))
+ .authorities(authorities(EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN, "FB_4", "FB_5"));
+
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A).with(clientToken))
+ .andExpect(status().isForbidden());
+ }
+
+ @Test
+ @DisplayName("the DataCustodian admin reads any subscription, and gets 404 for an unknown one")
+ void admin_reads_any_subscription() throws Exception {
+ assertThat(fetch(SUBSCRIPTION_B, admin())).contains(USAGE_POINT_B.toString())
+ .doesNotContain(USAGE_POINT_A.toString());
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + UUID.randomUUID()).with(admin()))
+ .andExpect(status().isNotFound());
+ }
+
+ @Test
+ @DisplayName("a subscription with no UsagePoints is a valid empty feed, typed espi-feed/Subscription")
+ void empty_subscription_is_an_empty_feed() throws Exception {
+ String xml = fetch(EMPTY_SUBSCRIPTION, customer(EMPTY_SUBSCRIPTION, "FB=1_3_4_5"));
+
+ assertThat(xml)
+ .contains("href=\"" + BASE + "/Batch/Subscription/" + EMPTY_SUBSCRIPTION + "\" type=\"espi-feed/Subscription\"")
+ .doesNotContain(" entryResources(String xml) {
+ return Pattern.compile("rel=\"self\" href=\"[^\"]*\" type=\"espi-entry/(\\w+)\"").matcher(xml)
+ .results().map(match -> match.group(1)).toList();
+ }
+
+ /**
+ * Valid against atom.xsd + espi.xsd, apart from #278: ServiceCategory is written as the Java constant
+ * name ({@code ELECTRICITY}) instead of espi.xsd's {@code 0}. Remove the exception with #278.
+ */
+ private static void assertValid(String xml) {
+ EspiXmlSchemaValidator.Result result = EspiXmlSchemaValidator.instance().validate(xml);
+ assertThat(result.issues())
+ .as(String.join("\n", EspiXmlSchemaValidator.describe(result)))
+ .filteredOn(issue -> issue.severity() != EspiXmlSchemaValidator.Severity.WARNING)
+ .allSatisfy(issue -> assertThat(issue.message()).contains("ServiceCategory"));
+ }
+
+ /** A customer access token for the subscription, with interval metering + electricity and the extra FBs. */
+ private static RequestPostProcessor customer(UUID subscriptionId, String scope, String... extraFbs) {
+ String[] fbs = Arrays.copyOf(ENERGY_FBS, ENERGY_FBS.length + extraFbs.length);
+ System.arraycopy(extraFbs, 0, fbs, ENERGY_FBS.length, extraFbs.length);
+ return opaqueToken()
+ .attributes(attributes -> {
+ attributes.put("resourceURI", BASE + "/Batch/Subscription/" + subscriptionId);
+ attributes.put("scope", List.of(scope));
+ })
+ .authorities(authorities(fbs));
+ }
+
+ private static RequestPostProcessor admin() {
+ return opaqueToken().authorities(new SimpleGrantedAuthority("SCOPE_DataCustodian_Admin_Access"));
+ }
+
+ private static List authorities(String... names) {
+ return Arrays.stream(names).map(SimpleGrantedAuthority::new).toList();
+ }
+
+ private SubscriptionEntity subscription(UUID id, List usagePoints) {
+ String key = id.toString().substring(id.toString().length() - 4);
+ RetailCustomerEntity customer = new RetailCustomerEntity("batch" + key, "Sample", "Customer",
+ "batch" + key + "@example.com", RetailCustomerEntity.ROLE_USER);
+ customer.setPassword("not-used");
+ customer.setEnabled(Boolean.TRUE);
+
+ ApplicationInformationEntity application = new ApplicationInformationEntity();
+ application.setClientId("batch-client-" + key);
+ application.setDataCustodianId("data_custodian");
+ application.setGrantTypes(new HashSet<>(Set.of(GrantType.AUTHORIZATION_CODE)));
+
+ AuthorizationEntity authorization = new AuthorizationEntity();
+ authorization.setAccessToken("token-" + id);
+ authorization.setStatus(AuthorizationEntity.STATUS_ACTIVE);
+
+ SubscriptionEntity subscription = new SubscriptionEntity(id);
+ subscription.setRetailCustomer(retailCustomerRepository.save(customer));
+ subscription.setApplicationInformation(applicationInformationRepository.save(application));
+ subscription.setAuthorization(authorizationRepository.save(authorization));
+ subscription.setUsagePoints(usagePoints);
+ return subscription;
+ }
+
+ /** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 30 days ago. */
+ private static UsagePointEntity usagePointA(long now) {
+ UsagePointEntity usagePoint = new UsagePointEntity();
+ usagePoint.setId(USAGE_POINT_A);
+ usagePoint.setDescription("Sample residential electric service");
+ usagePoint.setStatus((short) 1);
+ usagePoint.setServiceCategory(ServiceCategory.ELECTRICITY);
+
+ TimeConfigurationEntity localTime = new TimeConfigurationEntity();
+ localTime.setId(LOCAL_TIME_A);
+ localTime.setTzOffset(-18_000L);
+ localTime.setDstOffset(3_600L);
+ localTime.setDstStartRule(new byte[]{0x36, 0x0E, 0x20, 0x00});
+ localTime.setDstEndRule(new byte[]{(byte) 0xB4, 0x0E, 0x20, 0x00});
+ usagePoint.setLocalTimeParameters(localTime);
+
+ ReadingTypeEntity readingType = new ReadingTypeEntity();
+ readingType.setId(READING_TYPE_A);
+ readingType.setAccumulationBehaviour("4");
+ readingType.setCommodity("1");
+ readingType.setFlowDirection("1");
+ readingType.setIntervalLength(3_600L);
+ readingType.setKind("12");
+ readingType.setPowerOfTenMultiplier("-3");
+ readingType.setUom("72");
+
+ MeterReadingEntity meterReading = new MeterReadingEntity();
+ meterReading.setId(METER_READING_A);
+ meterReading.setUsagePoint(usagePoint);
+ meterReading.setReadingType(readingType);
+ meterReading.getIntervalBlocks().add(block(RECENT_BLOCK, meterReading, now - DAY));
+ meterReading.getIntervalBlocks().add(block(OLD_BLOCK, meterReading, now - 30 * DAY));
+ usagePoint.getMeterReadings().add(meterReading);
+
+ UsageSummaryEntity summary = new UsageSummaryEntity();
+ summary.setId(USAGE_SUMMARY_A);
+ summary.setUsagePoint(usagePoint);
+ summary.setBillingPeriod(new DateTimeInterval(30 * DAY, now - 30 * DAY));
+ summary.setStatusTimeStamp(now);
+ usagePoint.getUsageSummaries().add(summary);
+
+ ElectricPowerQualitySummaryEntity quality = new ElectricPowerQualitySummaryEntity();
+ quality.setId(QUALITY_SUMMARY_A);
+ quality.setUsagePoint(usagePoint);
+ quality.setSummaryInterval(new DateTimeInterval(30 * DAY, now - 30 * DAY));
+ quality.setMeasurementProtocol((short) 0);
+ quality.setMainsVoltage(240_000L);
+ quality.setFlickerPlt(0L);
+ quality.setFlickerPst(0L);
+ quality.setHarmonicVoltage(0L);
+ quality.setLongInterruptions(0L);
+ quality.setPowerFrequency(0L);
+ quality.setRapidVoltageChanges(0L);
+ quality.setShortInterruptions(0L);
+ quality.setSupplyVoltageDips(0L);
+ quality.setSupplyVoltageImbalance(0L);
+ quality.setSupplyVoltageVariations(0L);
+ quality.setTempOvervoltage(0L);
+ usagePoint.getElectricPowerQualitySummaries().add(quality);
+ return usagePoint;
+ }
+
+ private static IntervalBlockEntity block(UUID id, MeterReadingEntity meterReading, long start) {
+ IntervalBlockEntity block = new IntervalBlockEntity();
+ block.setId(id);
+ block.setMeterReading(meterReading);
+ block.setInterval(new DateTimeInterval(DAY, start));
+ IntervalReadingEntity reading = new IntervalReadingEntity();
+ reading.setIntervalBlock(block);
+ reading.setTimePeriod(new DateTimeInterval(3_600L, start));
+ reading.setValue(1_250_000L);
+ block.getIntervalReadings().add(reading);
+ return block;
+ }
+}
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
index 163928bd..17f00264 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
@@ -134,4 +134,43 @@ void emptySubscriptionDenied() {
assertThat(scope.isDenied()).isTrue();
}
+
+ @Test
+ @DisplayName("canReadSubscription: the admin, or a customer token for exactly that subscription (#279)")
+ void canReadSubscription() {
+ UUID mine = UUID.fromString("11111111-2222-5333-8444-555555555555");
+ UUID other = UUID.fromString("11111111-2222-5333-8444-666666666666");
+ Authentication customer = auth(Map.of("resourceURI", EspiBatchUri.batchSubscription(BASE, mine)), "FB_4");
+ Authentication clientToken = auth(Map.of("resourceURI", EspiBatchUri.batchSubscription(BASE, mine)),
+ "ESPI_CLIENT_ACCESS_TOKEN", "FB_4");
+ Authentication bulk = auth(Map.of("resourceURI", EspiBatchUri.batchBulk(BASE, "BULK_1")), "FB_4");
+ Authentication admin = auth(Map.of("active", true), "SCOPE_DataCustodian_Admin_Access");
+
+ assertThat(List.of(resolver.canReadSubscription(customer, mine), resolver.canReadSubscription(admin, other)))
+ .containsOnly(true);
+ assertThat(List.of(
+ resolver.canReadSubscription(customer, other),
+ resolver.canReadSubscription(clientToken, mine),
+ resolver.canReadSubscription(bulk, mine),
+ resolver.canReadSubscription(null, mine),
+ resolver.canReadSubscription(customer, null)))
+ .containsOnly(false);
+ verifyNoInteractions(subscriptionRepository);
+ }
+
+ @Test
+ @DisplayName("espiScope: the FB scope among the token's scopes, with its HistoryLength; none for FB=34_35 alone")
+ void espiScope() {
+ assertThat(resolver.espiScope(auth(Map.of("scope", List.of("openid", "FB=4_5_16;HistoryLength=86400")))))
+ .hasValueSatisfying(scope -> assertThat(scope)
+ .returns(86_400, org.greenbuttonalliance.espi.common.scope.EspiScope::historyLength)
+ .returns(true, s -> s.containsFunctionBlock(16)));
+ assertThat(resolver.espiScope(auth(Map.of("scope", "FB=4_5 openid")))).isPresent();
+ assertThat(List.of(
+ resolver.espiScope(auth(Map.of("scope", List.of("FB=34_35")))),
+ resolver.espiScope(auth(Map.of("scope", List.of("FB=4_x")))),
+ resolver.espiScope(auth(Map.of("active", true))),
+ resolver.espiScope(null)))
+ .allSatisfy(result -> assertThat(result).isEmpty());
+ }
}
From 59130b9f7c3e56ca11fc5ca77aa632b87518d1d8 Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 07:47:34 -0500
Subject: [PATCH 2/9] fix(datacustodian): apply HistoryLength to summaries in
Batch/Subscription (#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
---
.../web/api/SubscriptionFeedAssembler.java | 26 +++++++----
.../api/BatchSubscriptionIntegrationTest.java | 45 +++++++++++++------
2 files changed, 50 insertions(+), 21 deletions(-)
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index 305f2b0d..eafa4976 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -68,7 +68,8 @@
* links to the resources it refers to that are in the feed.
*
* {@code HistoryLength} (REQ.21: "the amount of historical information available from the Data
- * Custodian in seconds") drops IntervalBlocks that ended before now minus that length. {@code BlockDuration}
+ * Custodian in seconds") drops IntervalBlocks, UsageSummaries and ElectricPowerQualitySummaries whose interval
+ * ended before now minus that length. {@code BlockDuration}
* describes the blocks and selects nothing.
*/
@Component
@@ -141,9 +142,14 @@ private List entries(SubscriptionEntity subscription, String resource
for (UsagePointEntity usagePoint : subscription.getUsagePoints()) {
String usagePointFeed = subscriptionHref + "/UsagePoint";
String usagePointHref = usagePointFeed + "/" + usagePoint.getId();
- List summaries = grants.usageSummaries() ? usagePoint.getUsageSummaries() : List.of();
- List qualitySummaries =
- grants.powerQualitySummaries() ? usagePoint.getElectricPowerQualitySummaries() : List.of();
+ List summaries = !grants.usageSummaries() ? List.of()
+ : usagePoint.getUsageSummaries().stream()
+ .filter(summary -> withinHistory(summary.getBillingPeriod(), earliestEnd))
+ .toList();
+ List qualitySummaries = !grants.powerQualitySummaries() ? List.of()
+ : usagePoint.getElectricPowerQualitySummaries().stream()
+ .filter(summary -> withinHistory(summary.getSummaryInterval(), earliestEnd))
+ .toList();
TimeConfigurationEntity localTime = usagePoint.getLocalTimeParameters();
List usagePointRelated = new ArrayList<>();
@@ -192,7 +198,7 @@ private void addMeterReading(List entries, MeterReadingEntity meterRe
String meterReadingHref = meterReadingFeed + "/" + meterReading.getId();
ReadingTypeEntity readingType = meterReading.getReadingType();
List blocks = meterReading.getIntervalBlocks().stream()
- .filter(block -> withinHistory(block, earliestEnd))
+ .filter(block -> withinHistory(block.getInterval(), earliestEnd))
.toList();
List meterReadingRelated = new ArrayList<>();
@@ -217,9 +223,13 @@ private void addMeterReading(List entries, MeterReadingEntity meterRe
}
}
- /** A block without an interval is kept: there is nothing to measure it against. */
- private static boolean withinHistory(IntervalBlockEntity block, Long earliestEnd) {
- DateTimeInterval interval = block.getInterval();
+ /**
+ * Whether a resource covering {@code interval} (an IntervalBlock's interval, a UsageSummary's billing period
+ * or an ElectricPowerQualitySummary's summary interval) ends within {@code HistoryLength}. One rule for every
+ * time-bounded resource in the feed. A resource without an interval is kept: there is nothing to measure it
+ * against.
+ */
+ private static boolean withinHistory(DateTimeInterval interval, Long earliestEnd) {
if (earliestEnd == null || interval == null || interval.getStart() == null) {
return true;
}
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index 376877d9..bb255d61 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -94,6 +94,8 @@ class BatchSubscriptionIntegrationTest {
private static final UUID OLD_BLOCK = UUID.fromString("7b5be2d2-9a1c-5e66-b1b1-3e2d4f5a6b02");
private static final UUID USAGE_SUMMARY_A = UUID.fromString("8c6cf3e3-ab2d-5f77-82c2-4f3e5a6b7c01");
private static final UUID QUALITY_SUMMARY_A = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d01");
+ private static final UUID OLD_USAGE_SUMMARY = UUID.fromString("8c6cf3e3-ab2d-5f77-82c2-4f3e5a6b7c02");
+ private static final UUID OLD_QUALITY_SUMMARY = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d02");
private static final UUID LOCAL_TIME_A = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e01");
@Autowired
@@ -154,7 +156,8 @@ void customer_token_gets_its_subscription() throws Exception {
"")
.doesNotContain(USAGE_POINT_B.toString(), "", "xsi:type");
assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
- "IntervalBlock", "IntervalBlock", "UsageSummary", "ElectricPowerQualitySummary", "LocalTimeParameters");
+ "IntervalBlock", "IntervalBlock", "UsageSummary", "UsageSummary", "ElectricPowerQualitySummary",
+ "ElectricPowerQualitySummary", "LocalTimeParameters");
assertValid(xml);
}
@@ -171,11 +174,15 @@ void summaries_need_their_function_blocks() throws Exception {
}
@Test
- @DisplayName("HistoryLength (seconds) leaves out IntervalBlocks that ended before now minus that length")
- void history_length_limits_interval_blocks() throws Exception {
- String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5;HistoryLength=" + (7 * DAY)));
+ @DisplayName("HistoryLength (seconds) leaves out IntervalBlocks and summaries that ended before now minus that length")
+ void history_length_limits_time_bounded_resources() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (7 * DAY), "FB_16", "FB_17"));
- assertThat(xml).contains(RECENT_BLOCK.toString()).doesNotContain(OLD_BLOCK.toString());
+ assertThat(xml)
+ .contains(RECENT_BLOCK.toString(), USAGE_SUMMARY_A.toString(), QUALITY_SUMMARY_A.toString())
+ .doesNotContain(OLD_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
+ assertValid(xml);
}
@Test
@@ -290,7 +297,8 @@ private SubscriptionEntity subscription(UUID id, List usagePoi
return subscription;
}
- /** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 30 days ago. */
+ /** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 30 days ago; one
+ * UsageSummary and one ElectricPowerQualitySummary ending now, one of each ending 60 days ago. */
private static UsagePointEntity usagePointA(long now) {
UsagePointEntity usagePoint = new UsagePointEntity();
usagePoint.setId(USAGE_POINT_A);
@@ -324,17 +332,29 @@ private static UsagePointEntity usagePointA(long now) {
meterReading.getIntervalBlocks().add(block(OLD_BLOCK, meterReading, now - 30 * DAY));
usagePoint.getMeterReadings().add(meterReading);
+ usagePoint.getUsageSummaries().add(usageSummary(USAGE_SUMMARY_A, usagePoint, now - 30 * DAY, now));
+ usagePoint.getUsageSummaries().add(usageSummary(OLD_USAGE_SUMMARY, usagePoint, now - 90 * DAY, now));
+ usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(QUALITY_SUMMARY_A, usagePoint, now - 30 * DAY));
+ usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(OLD_QUALITY_SUMMARY, usagePoint, now - 90 * DAY));
+ return usagePoint;
+ }
+
+ /** A 30-day billing period starting at {@code start}. */
+ private static UsageSummaryEntity usageSummary(UUID id, UsagePointEntity usagePoint, long start, long now) {
UsageSummaryEntity summary = new UsageSummaryEntity();
- summary.setId(USAGE_SUMMARY_A);
+ summary.setId(id);
summary.setUsagePoint(usagePoint);
- summary.setBillingPeriod(new DateTimeInterval(30 * DAY, now - 30 * DAY));
+ summary.setBillingPeriod(new DateTimeInterval(30 * DAY, start));
summary.setStatusTimeStamp(now);
- usagePoint.getUsageSummaries().add(summary);
+ return summary;
+ }
+ /** A 30-day summary interval starting at {@code start}. */
+ private static ElectricPowerQualitySummaryEntity qualitySummary(UUID id, UsagePointEntity usagePoint, long start) {
ElectricPowerQualitySummaryEntity quality = new ElectricPowerQualitySummaryEntity();
- quality.setId(QUALITY_SUMMARY_A);
+ quality.setId(id);
quality.setUsagePoint(usagePoint);
- quality.setSummaryInterval(new DateTimeInterval(30 * DAY, now - 30 * DAY));
+ quality.setSummaryInterval(new DateTimeInterval(30 * DAY, start));
quality.setMeasurementProtocol((short) 0);
quality.setMainsVoltage(240_000L);
quality.setFlickerPlt(0L);
@@ -348,8 +368,7 @@ private static UsagePointEntity usagePointA(long now) {
quality.setSupplyVoltageImbalance(0L);
quality.setSupplyVoltageVariations(0L);
quality.setTempOvervoltage(0L);
- usagePoint.getElectricPowerQualitySummaries().add(quality);
- return usagePoint;
+ return quality;
}
private static IntervalBlockEntity block(UUID id, MeterReadingEntity meterReading, long start) {
From f56a79895ac3b0ec58b4d14cdd6f544fe41d9d6d Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 14:08:23 -0500
Subject: [PATCH 3/9] fix(datacustodian): Batch/Subscription query range,
HistoryLength ceiling, 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
---
.../web/api/BatchSubscriptionController.java | 42 ++++-
.../web/api/SubscriptionFeedAssembler.java | 169 +++++++++++++-----
.../web/api/scope/ScopeResolver.java | 45 +++--
.../api/BatchSubscriptionIntegrationTest.java | 154 +++++++++++++---
.../web/api/scope/ScopeResolverTest.java | 28 +--
5 files changed, 343 insertions(+), 95 deletions(-)
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
index 4bb17df6..a1264fe8 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -25,11 +25,13 @@
import io.swagger.v3.oas.annotations.security.SecurityRequirement;
import io.swagger.v3.oas.annotations.tags.Tag;
import org.greenbuttonalliance.espi.common.dto.atom.AtomFeedDto;
-import org.greenbuttonalliance.espi.common.scope.EspiScope;
import org.greenbuttonalliance.espi.common.service.impl.UsageExportService;
import org.greenbuttonalliance.espi.datacustodian.config.UsageFunctionBlockAuthorities;
import org.greenbuttonalliance.espi.datacustodian.web.api.SubscriptionFeedAssembler.Grants;
+import org.greenbuttonalliance.espi.datacustodian.web.api.SubscriptionFeedAssembler.Range;
import org.greenbuttonalliance.espi.datacustodian.web.api.scope.ScopeResolver;
+import org.springframework.format.annotation.DateTimeFormat;
+import org.springframework.format.annotation.DateTimeFormat.ISO;
import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
@@ -37,11 +39,14 @@
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import org.springframework.web.server.ResponseStatusException;
import org.springframework.web.servlet.support.ServletUriComponentsBuilder;
import java.io.ByteArrayOutputStream;
+import java.time.Instant;
+import java.time.OffsetDateTime;
import java.util.UUID;
/**
@@ -82,6 +87,7 @@ public BatchSubscriptionController(ScopeResolver scopeResolver, SubscriptionFeed
+ " IntervalBlocks, summaries and LocalTimeParameters, as granted by the token's scope",
responses = {
@ApiResponse(responseCode = "200", description = "The subscription's feed"),
+ @ApiResponse(responseCode = "400", description = "A query parameter is not an xs:dateTime"),
@ApiResponse(responseCode = "401", description = "Unauthorized"),
@ApiResponse(responseCode = "403", description = "Not this token's subscription"),
@ApiResponse(responseCode = "404", description = "No such subscription (DataCustodian admin only)")
@@ -90,14 +96,28 @@ public BatchSubscriptionController(ScopeResolver scopeResolver, SubscriptionFeed
public ResponseEntity getSubscription(
@Parameter(description = "The subscription id from the token's resourceURI", required = true)
@PathVariable UUID subscriptionId,
+ @Parameter(description = "Return data whose interval ends after this time (xs:dateTime)."
+ + " Without published-min and published-max: the last 24 hours")
+ @RequestParam(name = "published-min", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime publishedMin,
+ @Parameter(description = "Return data whose interval starts at or before this time (xs:dateTime)")
+ @RequestParam(name = "published-max", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime publishedMax,
+ @Parameter(description = "Return data whose atom:updated is at or after this time (xs:dateTime)")
+ @RequestParam(name = "updated-min", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime updatedMin,
+ @Parameter(description = "Return data whose atom:updated is at or before this time (xs:dateTime)")
+ @RequestParam(name = "updated-max", required = false) @DateTimeFormat(iso = ISO.DATE_TIME)
+ OffsetDateTime updatedMax,
Authentication authentication) {
if (!scopeResolver.canReadSubscription(authentication, subscriptionId)) {
throw new ResponseStatusException(HttpStatus.FORBIDDEN);
}
+ Range range = new Range(instant(publishedMin), instant(publishedMax), instant(updatedMin), instant(updatedMax));
String feedHref = ServletUriComponentsBuilder.fromCurrentRequestUri().toUriString();
String resourceBase = feedHref.substring(0, feedHref.indexOf(BATCH_SUBSCRIPTION));
- AtomFeedDto feed = assembler.build(subscriptionId, resourceBase, feedHref, grants(authentication))
+ AtomFeedDto feed = assembler.build(subscriptionId, resourceBase, feedHref, grants(authentication), range)
.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
ByteArrayOutputStream out = new ByteArrayOutputStream();
@@ -107,15 +127,27 @@ public ResponseEntity getSubscription(
.body(out.toByteArray());
}
- /** The admin sees everything; a customer token sees what its Function Blocks and HistoryLength grant. */
+ /**
+ * The admin sees everything; a customer token sees what its Function Blocks grant, no further back than its
+ * HistoryLength. An FB scope that does not parse is refused (403) rather than read as "no limit".
+ */
private Grants grants(Authentication authentication) {
if (scopeResolver.isAdmin(authentication)) {
return Grants.all();
}
- Integer historyLength = scopeResolver.espiScope(authentication).map(EspiScope::historyLength).orElse(null);
+ Long historyLength;
+ try {
+ historyLength = scopeResolver.historyLengthSeconds(authentication).orElse(null);
+ } catch (IllegalArgumentException ex) {
+ throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Unreadable ESPI scope");
+ }
return new Grants(
UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.USAGE_SUMMARY),
UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.POWER_QUALITY),
- historyLength == null ? null : historyLength.longValue());
+ historyLength);
+ }
+
+ private static Instant instant(OffsetDateTime time) {
+ return time == null ? null : time.toInstant();
}
}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index eafa4976..93759bac 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -20,6 +20,7 @@
package org.greenbuttonalliance.espi.datacustodian.web.api;
import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
+import org.greenbuttonalliance.espi.common.domain.common.IdentifiedObject;
import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
import org.greenbuttonalliance.espi.common.domain.usage.MeterReadingEntity;
@@ -44,37 +45,56 @@
import org.springframework.transaction.annotation.Transactional;
import java.time.Clock;
+import java.time.Instant;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
import java.util.ArrayList;
+import java.util.Comparator;
import java.util.HashSet;
import java.util.List;
import java.util.Optional;
import java.util.Set;
import java.util.UUID;
+import java.util.function.Function;
/**
* Builds {@code Batch/Subscription/{subscriptionId}} (#279): one Atom feed with the energy usage data of a
* subscription. The caller has already checked who may read it ({@code ScopeResolver#canReadSubscription}).
*
- * Entries, in the order of certified feeds, for each UsagePoint the customer selected:
+ * Entries, in the order of certified feeds, for each UsagePoint the customer selected (UsagePoints and
+ * MeterReadings by id, time-bounded resources by interval start):
*
* - the UsagePoint;
* - each MeterReading, its ReadingType (once in the feed, even if shared) and its IntervalBlocks;
* - the UsageSummaries and ElectricPowerQualitySummaries, when the token's Function Blocks grant them;
- * - its LocalTimeParameters.
+ * - its LocalTimeParameters (once in the feed, even if shared).
*
*
* Hrefs are subscription-scoped ({@code .../Subscription/{id}/UsagePoint/{id}/...}); ReadingType and
* LocalTimeParameters are root resources. Each entry has {@code self} and {@code up}, plus {@code related}
* links to the resources it refers to that are in the feed.
*
- * {@code HistoryLength} (REQ.21: "the amount of historical information available from the Data
- * Custodian in seconds") drops IntervalBlocks, UsageSummaries and ElectricPowerQualitySummaries whose interval
- * ended before now minus that length. {@code BlockDuration}
+ *
Which IntervalBlocks, UsageSummaries and ElectricPowerQualitySummaries are returned (the "time-bounded"
+ * resources, by their interval, billing period or summary interval, whose end is start + duration):
+ *
+ * - {@code published-min}/{@code published-max} select those whose interval overlaps the range;
+ * - without either, the default is the last 24 hours, by overlap, plus, for each UsagePoint, its most
+ * recent UsageSummary and its most recent ElectricPowerQualitySummary (summary intervals rarely line up
+ * with a 24-hour window);
+ * - {@code updated-min}/{@code updated-max} select by {@code atom:updated};
+ * - {@code HistoryLength} (REQ.21: "the amount of historical information available from the Data
+ * Custodian in seconds") is a ceiling, not a selection: nothing that ended before now minus that length
+ * is returned, whatever the range asks for.
+ *
+ * A resource without an interval is kept: there is nothing to measure it against. {@code BlockDuration}
* describes the blocks and selects nothing.
*/
@Component
public class SubscriptionFeedAssembler {
+ /** The default range when the request has neither {@code published-min} nor {@code published-max}. */
+ static final long DEFAULT_WINDOW_SECONDS = 24 * 60 * 60L;
+
/** What the token grants, beyond reading the subscription at all. */
public record Grants(boolean usageSummaries, boolean powerQualitySummaries, Long historyLengthSeconds) {
@@ -83,6 +103,16 @@ public static Grants all() {
}
}
+ /** The request's ESPI query parameters (REQ.21.6.2.8); each may be null. */
+ public record Range(Instant publishedMin, Instant publishedMax, Instant updatedMin, Instant updatedMax) {
+
+ public static Range none() {
+ return new Range(null, null, null, null);
+ }
+ }
+
+ private static final Comparator BY_ID = Comparator.comparing(IdentifiedObject::getId);
+
private final SubscriptionRepository subscriptionRepository;
private final UsageExportService usageExportService;
private final UsagePointMapper usagePointMapper;
@@ -92,7 +122,7 @@ public static Grants all() {
private final UsageSummaryMapper usageSummaryMapper;
private final ElectricPowerQualitySummaryMapper powerQualitySummaryMapper;
private final TimeConfigurationMapper timeConfigurationMapper;
- private Clock clock = Clock.systemUTC();
+ private final Clock clock = Clock.systemUTC();
public SubscriptionFeedAssembler(SubscriptionRepository subscriptionRepository,
UsageExportService usageExportService,
@@ -114,11 +144,6 @@ public SubscriptionFeedAssembler(SubscriptionRepository subscriptionRepository,
this.timeConfigurationMapper = timeConfigurationMapper;
}
- /** For tests: the clock {@code HistoryLength} is measured from. */
- void setClock(Clock clock) {
- this.clock = clock;
- }
-
/**
* The subscription's feed, or empty if there is no such subscription.
*
@@ -126,30 +151,29 @@ void setClock(Clock clock) {
* @param feedHref the request's absolute URL (the feed's self link)
*/
@Transactional(readOnly = true)
- public Optional build(UUID subscriptionId, String resourceBase, String feedHref, Grants grants) {
+ public Optional build(UUID subscriptionId, String resourceBase, String feedHref, Grants grants,
+ Range range) {
return subscriptionRepository.findById(subscriptionId)
.map(subscription -> usageExportService.buildFeedOf(feedHref, "Subscription",
- "Green Button Subscription Feed", entries(subscription, resourceBase, grants)));
+ "Green Button Subscription Feed",
+ entries(subscription, resourceBase, grants, Selection.of(range, grants, clock.instant()))));
}
- private List entries(SubscriptionEntity subscription, String resourceBase, Grants grants) {
+ private List entries(SubscriptionEntity subscription, String resourceBase, Grants grants,
+ Selection selection) {
String subscriptionHref = resourceBase + "/Subscription/" + subscription.getId();
- Long earliestEnd = grants.historyLengthSeconds() == null ? null
- : clock.instant().getEpochSecond() - grants.historyLengthSeconds();
Set readingTypesInFeed = new HashSet<>();
+ Set localTimesInFeed = new HashSet<>();
List entries = new ArrayList<>();
- for (UsagePointEntity usagePoint : subscription.getUsagePoints()) {
+ for (UsagePointEntity usagePoint : sorted(subscription.getUsagePoints(), BY_ID)) {
String usagePointFeed = subscriptionHref + "/UsagePoint";
String usagePointHref = usagePointFeed + "/" + usagePoint.getId();
List summaries = !grants.usageSummaries() ? List.of()
- : usagePoint.getUsageSummaries().stream()
- .filter(summary -> withinHistory(summary.getBillingPeriod(), earliestEnd))
- .toList();
+ : selection.summaries(usagePoint.getUsageSummaries(), UsageSummaryEntity::getBillingPeriod);
List qualitySummaries = !grants.powerQualitySummaries() ? List.of()
- : usagePoint.getElectricPowerQualitySummaries().stream()
- .filter(summary -> withinHistory(summary.getSummaryInterval(), earliestEnd))
- .toList();
+ : selection.summaries(usagePoint.getElectricPowerQualitySummaries(),
+ ElectricPowerQualitySummaryEntity::getSummaryInterval);
TimeConfigurationEntity localTime = usagePoint.getLocalTimeParameters();
List usagePointRelated = new ArrayList<>();
@@ -170,8 +194,8 @@ private List entries(SubscriptionEntity subscription, String resource
entries.add(new FeedEntry(usagePoint, usagePointMapper.toDto(usagePoint), usagePointHref,
usagePointFeed, usagePointRelated));
- for (MeterReadingEntity meterReading : usagePoint.getMeterReadings()) {
- addMeterReading(entries, meterReading, usagePointHref, resourceBase, earliestEnd, readingTypesInFeed);
+ for (MeterReadingEntity meterReading : sorted(usagePoint.getMeterReadings(), BY_ID)) {
+ addMeterReading(entries, meterReading, usagePointHref, resourceBase, selection, readingTypesInFeed);
}
for (UsageSummaryEntity summary : summaries) {
String feed = usagePointHref + "/UsageSummary";
@@ -183,7 +207,7 @@ private List entries(SubscriptionEntity subscription, String resource
entries.add(new FeedEntry(summary, powerQualitySummaryMapper.toDto(summary),
feed + "/" + summary.getId(), feed, List.of()));
}
- if (localTime != null) {
+ if (localTime != null && localTimesInFeed.add(localTime.getId())) {
String feed = resourceBase + "/LocalTimeParameters";
entries.add(new FeedEntry(localTime, timeConfigurationMapper.toDto(localTime),
feed + "/" + localTime.getId(), feed, List.of()));
@@ -193,13 +217,11 @@ private List entries(SubscriptionEntity subscription, String resource
}
private void addMeterReading(List entries, MeterReadingEntity meterReading, String usagePointHref,
- String resourceBase, Long earliestEnd, Set readingTypesInFeed) {
+ String resourceBase, Selection selection, Set readingTypesInFeed) {
String meterReadingFeed = usagePointHref + "/MeterReading";
String meterReadingHref = meterReadingFeed + "/" + meterReading.getId();
ReadingTypeEntity readingType = meterReading.getReadingType();
- List blocks = meterReading.getIntervalBlocks().stream()
- .filter(block -> withinHistory(block.getInterval(), earliestEnd))
- .toList();
+ List blocks = selection.blocks(meterReading.getIntervalBlocks());
List meterReadingRelated = new ArrayList<>();
if (readingType != null) {
@@ -223,21 +245,84 @@ private void addMeterReading(List entries, MeterReadingEntity meterRe
}
}
- /**
- * Whether a resource covering {@code interval} (an IntervalBlock's interval, a UsageSummary's billing period
- * or an ElectricPowerQualitySummary's summary interval) ends within {@code HistoryLength}. One rule for every
- * time-bounded resource in the feed. A resource without an interval is kept: there is nothing to measure it
- * against.
- */
- private static boolean withinHistory(DateTimeInterval interval, Long earliestEnd) {
- if (earliestEnd == null || interval == null || interval.getStart() == null) {
- return true;
- }
- long end = interval.getStart() + (interval.getDuration() == null ? 0 : interval.getDuration());
- return end > earliestEnd;
+ private static List sorted(List items, Comparator super T> order) {
+ return items == null ? List.of() : items.stream().sorted(order).toList();
}
private static LinkDto related(String href, String type) {
return new LinkDto("related", href, type);
}
+
+ /**
+ * Which time-bounded resources a request gets, in epoch seconds. {@code from}/{@code to} bound the overlap
+ * (null = open); {@code ceiling} is now minus {@code HistoryLength} (null = no limit).
+ */
+ private record Selection(Long from, Long to, Long ceiling, Long updatedMin, Long updatedMax,
+ boolean defaultWindow) {
+
+ static Selection of(Range range, Grants grants, Instant now) {
+ long nowSeconds = now.getEpochSecond();
+ Long ceiling = grants.historyLengthSeconds() == null ? null : nowSeconds - grants.historyLengthSeconds();
+ boolean defaultWindow = range.publishedMin() == null && range.publishedMax() == null;
+ Long from = defaultWindow ? Long.valueOf(nowSeconds - DEFAULT_WINDOW_SECONDS) : seconds(range.publishedMin());
+ return new Selection(from, defaultWindow ? null : seconds(range.publishedMax()), ceiling,
+ seconds(range.updatedMin()), seconds(range.updatedMax()), defaultWindow);
+ }
+
+ /** The blocks in the range, by interval start. */
+ List blocks(List blocks) {
+ return available(blocks, IntervalBlockEntity::getInterval).stream()
+ .filter(block -> overlaps(block.getInterval()))
+ .toList();
+ }
+
+ /** The summaries in the range, by interval start; by default also the most recent one available. */
+ List summaries(List summaries, Function interval) {
+ List available = available(summaries, interval);
+ List selected = new ArrayList<>(available.stream().filter(s -> overlaps(interval.apply(s))).toList());
+ if (defaultWindow && !available.isEmpty() && !selected.contains(available.getLast())) {
+ selected.add(available.getLast());
+ }
+ return selected;
+ }
+
+ /** Within HistoryLength and the updated-min/max range, sorted by interval start (no interval first). */
+ private List available(List items, Function interval) {
+ Comparator byStart = Comparator.comparing(item -> start(interval.apply(item)),
+ Comparator.nullsFirst(Comparator.naturalOrder()));
+ return sorted(items, byStart.thenComparing(IdentifiedObject::getId)).stream()
+ .filter(item -> endsAfter(interval.apply(item), ceiling) && updatedInRange(item.getUpdated()))
+ .toList();
+ }
+
+ private boolean overlaps(DateTimeInterval interval) {
+ if (start(interval) == null) {
+ return true;
+ }
+ return endsAfter(interval, from) && (to == null || interval.getStart() <= to);
+ }
+
+ private boolean updatedInRange(LocalDateTime updated) {
+ if (updated == null) {
+ return updatedMin == null && updatedMax == null;
+ }
+ long seconds = updated.toEpochSecond(ZoneOffset.UTC);
+ return (updatedMin == null || seconds >= updatedMin) && (updatedMax == null || seconds <= updatedMax);
+ }
+
+ private static boolean endsAfter(DateTimeInterval interval, Long limit) {
+ if (limit == null || start(interval) == null) {
+ return true;
+ }
+ return interval.getStart() + (interval.getDuration() == null ? 0 : interval.getDuration()) > limit;
+ }
+
+ private static Long start(DateTimeInterval interval) {
+ return interval == null ? null : interval.getStart();
+ }
+
+ private static Long seconds(Instant instant) {
+ return instant == null ? null : instant.getEpochSecond();
+ }
+ }
}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
index 12e3c1d2..6f23d4c3 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
@@ -27,9 +27,11 @@
import org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal;
import org.springframework.stereotype.Component;
+import java.util.ArrayList;
import java.util.Collection;
import java.util.LinkedHashSet;
import java.util.List;
+import java.util.Objects;
import java.util.Optional;
import java.util.Set;
import java.util.UUID;
@@ -141,28 +143,42 @@ public boolean canReadSubscription(Authentication authentication, UUID subscript
}
/**
- * The token's ESPI scope (the {@code FB=...} scope string, with its {@code HistoryLength} and other
- * terms), or empty for the admin, a token without one, or a scope that does not parse.
+ * Every ESPI scope of the token (each {@code FB=...} scope string, with its {@code HistoryLength} and other
+ * terms), except the client access token's {@code FB=34_35}; empty for a token without one.
+ *
+ * @throws IllegalArgumentException if an FB scope does not parse: the caller must refuse the request rather
+ * than read it as "no limits" (fail closed)
*/
- public Optional espiScope(Authentication authentication) {
+ public List espiScopes(Authentication authentication) {
if (authentication == null || !(authentication.getPrincipal() instanceof OAuth2AuthenticatedPrincipal principal)) {
- return Optional.empty();
+ return List.of();
}
Object scope = principal.getAttribute("scope");
Collection> scopes = scope instanceof Collection> collection ? collection
: scope instanceof String s ? List.of(s.trim().split("\\s+")) : List.of();
+ List parsed = new ArrayList<>();
for (Object value : scopes) {
String text = value == null ? "" : value.toString().trim();
if (text.regionMatches(true, 0, "FB=", 0, 3)
&& !EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN_SCOPE.equals(text)) {
- try {
- return Optional.of(EspiScope.parse(text));
- } catch (IllegalArgumentException ex) {
- return Optional.empty();
- }
+ parsed.add(EspiScope.parse(text));
}
}
- return Optional.empty();
+ return parsed;
+ }
+
+ /**
+ * The token's {@code HistoryLength} in seconds: the shortest among its FB scopes, or empty if none states
+ * one.
+ *
+ * @throws IllegalArgumentException if an FB scope does not parse (see {@link #espiScopes})
+ */
+ public Optional historyLengthSeconds(Authentication authentication) {
+ return espiScopes(authentication).stream()
+ .map(EspiScope::historyLength)
+ .filter(Objects::nonNull)
+ .map(Integer::longValue)
+ .min(Long::compare);
}
/** Whether the caller holds the DataCustodian admin authority. */
@@ -179,13 +195,8 @@ private static boolean hasAuthority(Authentication authentication, String name)
return false;
}
- private boolean hasAdminAuthority(Authentication authentication) {
- for (GrantedAuthority authority : authentication.getAuthorities()) {
- if (ADMIN_AUTHORITY.equals(authority.getAuthority())) {
- return true;
- }
- }
- return false;
+ private static boolean hasAdminAuthority(Authentication authentication) {
+ return hasAuthority(authentication, ADMIN_AUTHORITY);
}
private static String stringAttribute(OAuth2AuthenticatedPrincipal principal, String name) {
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index bb255d61..e977c11c 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -51,10 +51,12 @@
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.test.context.ActiveProfiles;
import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.request.MockHttpServletRequestBuilder;
import org.springframework.test.web.servlet.request.RequestPostProcessor;
import org.springframework.transaction.annotation.Transactional;
import java.time.Instant;
+import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.List;
@@ -97,6 +99,13 @@ class BatchSubscriptionIntegrationTest {
private static final UUID OLD_USAGE_SUMMARY = UUID.fromString("8c6cf3e3-ab2d-5f77-82c2-4f3e5a6b7c02");
private static final UUID OLD_QUALITY_SUMMARY = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d02");
private static final UUID LOCAL_TIME_A = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e01");
+ private static final UUID SHARED_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a04");
+ private static final UUID SHARED_POINT_1 = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f503");
+ private static final UUID SHARED_POINT_2 = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f504");
+ private static final UUID SHARED_LOCAL_TIME = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e02");
+
+ /** When the fixtures were made, in epoch seconds. */
+ private long now;
@Autowired
private MockMvc mockMvc;
@@ -118,7 +127,7 @@ class BatchSubscriptionIntegrationTest {
@BeforeEach
void setUp() {
- long now = Instant.now().getEpochSecond();
+ now = Instant.now().getEpochSecond();
UsagePointEntity usagePointA = usagePointRepository.save(usagePointA(now));
UsagePointEntity usagePointB = new UsagePointEntity();
usagePointB.setId(USAGE_POINT_B);
@@ -132,7 +141,7 @@ void setUp() {
}
@Test
- @DisplayName("a customer token gets exactly its subscription's resources, in certified order, as valid ESPI XML")
+ @DisplayName("without query parameters: the last 24 hours, plus the latest summaries, in certified order, as valid ESPI XML")
void customer_token_gets_its_subscription() throws Exception {
String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"));
String subscription = BASE + "/Subscription/" + SUBSCRIPTION_A;
@@ -154,13 +163,65 @@ void customer_token_gets_its_subscription() throws Exception {
"href=\"" + usagePoint + "/UsageSummary/" + USAGE_SUMMARY_A + "\"",
"href=\"" + usagePoint + "/ElectricPowerQualitySummary/" + QUALITY_SUMMARY_A + "\"",
"")
- .doesNotContain(USAGE_POINT_B.toString(), "", "xsi:type");
+ .doesNotContain(USAGE_POINT_B.toString(), "", "xsi:type", OLD_BLOCK.toString(),
+ OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
+ // The UsageSummary's billing period runs to now (overlap); the power quality summary ended 5 days ago and
+ // is there as the UsagePoint's latest.
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
+ "IntervalBlock", "UsageSummary", "ElectricPowerQualitySummary", "LocalTimeParameters");
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("published-min/max select by interval overlap, with no latest-summary exception")
+ void published_range_selects_by_interval() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY), "published-max", ago(70 * DAY));
+
+ assertThat(xml)
+ .contains(OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString())
+ .doesNotContain(RECENT_BLOCK.toString(), OLD_BLOCK.toString(), USAGE_SUMMARY_A.toString(),
+ QUALITY_SUMMARY_A.toString());
+ assertValid(xml);
+ }
+
+ @Test
+ @DisplayName("a wide range returns every block and summary, sorted by interval start")
+ void entries_are_chronological() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY));
+
+ // The fixtures add the newer one first.
+ assertThat(List.of(
+ xml.indexOf(OLD_BLOCK.toString()) < xml.indexOf(RECENT_BLOCK.toString()),
+ xml.indexOf(OLD_USAGE_SUMMARY.toString()) < xml.indexOf(USAGE_SUMMARY_A.toString()),
+ xml.indexOf(OLD_QUALITY_SUMMARY.toString()) < xml.indexOf(QUALITY_SUMMARY_A.toString())))
+ .containsOnly(true);
assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
"IntervalBlock", "IntervalBlock", "UsageSummary", "UsageSummary", "ElectricPowerQualitySummary",
"ElectricPowerQualitySummary", "LocalTimeParameters");
assertValid(xml);
}
+ @Test
+ @DisplayName("updated-min/max select by atom:updated")
+ void updated_range_selects_by_atom_updated() throws Exception {
+ String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY), "updated-max", "2000-01-01T00:00:00Z");
+
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "MeterReading", "ReadingType",
+ "LocalTimeParameters");
+ }
+
+ @Test
+ @DisplayName("a query parameter that is not an xs:dateTime is a 400")
+ void malformed_query_parameter_is_bad_request() throws Exception {
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A)
+ .param("published-min", "yesterday")
+ .with(customer(SUBSCRIPTION_A, "FB=1_3_4_5")))
+ .andExpect(status().isBadRequest());
+ }
+
@Test
@DisplayName("without FB_16 and FB_17 there are no summaries, and no related links to them")
void summaries_need_their_function_blocks() throws Exception {
@@ -174,14 +235,52 @@ void summaries_need_their_function_blocks() throws Exception {
}
@Test
- @DisplayName("HistoryLength (seconds) leaves out IntervalBlocks and summaries that ended before now minus that length")
- void history_length_limits_time_bounded_resources() throws Exception {
- String xml = fetch(SUBSCRIPTION_A,
- customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (7 * DAY), "FB_16", "FB_17"));
-
- assertThat(xml)
+ @DisplayName("HistoryLength is a ceiling: nothing that ended before now minus it, whatever the range asks for")
+ void history_length_is_a_ceiling() throws Exception {
+ String wide = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (7 * DAY), "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY));
+ // By default the latest power quality summary is added, but not past the ceiling: it ended 5 days ago.
+ String latest = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (2 * DAY), "FB_16", "FB_17"));
+
+ assertThat(wide)
.contains(RECENT_BLOCK.toString(), USAGE_SUMMARY_A.toString(), QUALITY_SUMMARY_A.toString())
.doesNotContain(OLD_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
+ assertThat(latest)
+ .contains(RECENT_BLOCK.toString(), USAGE_SUMMARY_A.toString())
+ .doesNotContain(QUALITY_SUMMARY_A.toString(), OLD_QUALITY_SUMMARY.toString());
+ assertValid(wide);
+ }
+
+ @Test
+ @DisplayName("an FB scope that does not parse is refused, not read as 'no HistoryLength'")
+ void unreadable_scope_is_refused() throws Exception {
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A)
+ .with(customer(SUBSCRIPTION_A, "FB=4_x;HistoryLength=86400")))
+ .andExpect(status().isForbidden());
+ }
+
+ @Test
+ @DisplayName("a LocalTimeParameters shared by two UsagePoints is one entry, linked from both")
+ void shared_local_time_parameters_is_one_entry() throws Exception {
+ TimeConfigurationEntity shared = localTime(SHARED_LOCAL_TIME);
+ List usagePoints = new ArrayList<>();
+ for (UUID id : List.of(SHARED_POINT_1, SHARED_POINT_2)) {
+ UsagePointEntity usagePoint = new UsagePointEntity();
+ usagePoint.setId(id);
+ usagePoint.setServiceCategory(ServiceCategory.ELECTRICITY);
+ usagePoint.setLocalTimeParameters(shared);
+ usagePoints.add(usagePointRepository.save(usagePoint));
+ }
+ subscriptionRepository.saveAndFlush(subscription(SHARED_SUBSCRIPTION, usagePoints));
+
+ String xml = fetch(SHARED_SUBSCRIPTION, admin());
+
+ // It closes the first UsagePoint's group; the second UsagePoint only links to it.
+ assertThat(entryResources(xml)).containsExactly("UsagePoint", "LocalTimeParameters", "UsagePoint");
+ assertThat(Pattern.compile("rel=\"related\" href=\"" + BASE + "/LocalTimeParameters/" + SHARED_LOCAL_TIME)
+ .matcher(xml).results().count()).isEqualTo(2);
assertValid(xml);
}
@@ -229,12 +328,22 @@ void empty_subscription_is_an_empty_feed() throws Exception {
// --- helpers ------------------------------------------------------------------------------------------
- private String fetch(UUID subscriptionId, RequestPostProcessor token) throws Exception {
- return mockMvc.perform(get(BASE + "/Batch/Subscription/" + subscriptionId).with(token))
+ /** GET the subscription's feed, expecting 200; {@code params} are query parameter name/value pairs. */
+ private String fetch(UUID subscriptionId, RequestPostProcessor token, String... params) throws Exception {
+ MockHttpServletRequestBuilder request = get(BASE + "/Batch/Subscription/" + subscriptionId).with(token);
+ for (int i = 0; i + 1 < params.length; i += 2) {
+ request.param(params[i], params[i + 1]);
+ }
+ return mockMvc.perform(request)
.andExpect(status().isOk())
.andReturn().getResponse().getContentAsString();
}
+ /** {@code seconds} before the fixtures' now, as an xs:dateTime. */
+ private String ago(long seconds) {
+ return Instant.ofEpochSecond(now - seconds).toString();
+ }
+
/** The entries' resource names, in feed order (from each entry's self link type). */
private static List entryResources(String xml) {
return Pattern.compile("rel=\"self\" href=\"[^\"]*\" type=\"espi-entry/(\\w+)\"").matcher(xml)
@@ -298,7 +407,8 @@ private SubscriptionEntity subscription(UUID id, List usagePoi
}
/** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 30 days ago; one
- * UsageSummary and one ElectricPowerQualitySummary ending now, one of each ending 60 days ago. */
+ * UsageSummary ending now and one ElectricPowerQualitySummary ending 5 days ago, and one of each ending
+ * 60 days ago. Each collection gets its newer item first, so the feed's order comes from sorting. */
private static UsagePointEntity usagePointA(long now) {
UsagePointEntity usagePoint = new UsagePointEntity();
usagePoint.setId(USAGE_POINT_A);
@@ -306,13 +416,7 @@ private static UsagePointEntity usagePointA(long now) {
usagePoint.setStatus((short) 1);
usagePoint.setServiceCategory(ServiceCategory.ELECTRICITY);
- TimeConfigurationEntity localTime = new TimeConfigurationEntity();
- localTime.setId(LOCAL_TIME_A);
- localTime.setTzOffset(-18_000L);
- localTime.setDstOffset(3_600L);
- localTime.setDstStartRule(new byte[]{0x36, 0x0E, 0x20, 0x00});
- localTime.setDstEndRule(new byte[]{(byte) 0xB4, 0x0E, 0x20, 0x00});
- usagePoint.setLocalTimeParameters(localTime);
+ usagePoint.setLocalTimeParameters(localTime(LOCAL_TIME_A));
ReadingTypeEntity readingType = new ReadingTypeEntity();
readingType.setId(READING_TYPE_A);
@@ -334,11 +438,21 @@ private static UsagePointEntity usagePointA(long now) {
usagePoint.getUsageSummaries().add(usageSummary(USAGE_SUMMARY_A, usagePoint, now - 30 * DAY, now));
usagePoint.getUsageSummaries().add(usageSummary(OLD_USAGE_SUMMARY, usagePoint, now - 90 * DAY, now));
- usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(QUALITY_SUMMARY_A, usagePoint, now - 30 * DAY));
+ usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(QUALITY_SUMMARY_A, usagePoint, now - 35 * DAY));
usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(OLD_QUALITY_SUMMARY, usagePoint, now - 90 * DAY));
return usagePoint;
}
+ private static TimeConfigurationEntity localTime(UUID id) {
+ TimeConfigurationEntity localTime = new TimeConfigurationEntity();
+ localTime.setId(id);
+ localTime.setTzOffset(-18_000L);
+ localTime.setDstOffset(3_600L);
+ localTime.setDstStartRule(new byte[]{0x36, 0x0E, 0x20, 0x00});
+ localTime.setDstEndRule(new byte[]{(byte) 0xB4, 0x0E, 0x20, 0x00});
+ return localTime;
+ }
+
/** A 30-day billing period starting at {@code start}. */
private static UsageSummaryEntity usageSummary(UUID id, UsagePointEntity usagePoint, long start, long now) {
UsageSummaryEntity summary = new UsageSummaryEntity();
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
index 17f00264..db65cd7a 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
@@ -19,6 +19,7 @@
package org.greenbuttonalliance.espi.datacustodian.web.api.scope;
import org.greenbuttonalliance.espi.common.repositories.usage.SubscriptionRepository;
+import org.greenbuttonalliance.espi.common.scope.EspiScope;
import org.greenbuttonalliance.espi.common.uri.EspiBatchUri;
import org.junit.jupiter.api.DisplayName;
import org.junit.jupiter.api.Test;
@@ -31,6 +32,7 @@
import java.util.UUID;
import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verifyNoInteractions;
import static org.mockito.Mockito.when;
@@ -159,18 +161,22 @@ void canReadSubscription() {
}
@Test
- @DisplayName("espiScope: the FB scope among the token's scopes, with its HistoryLength; none for FB=34_35 alone")
- void espiScope() {
- assertThat(resolver.espiScope(auth(Map.of("scope", List.of("openid", "FB=4_5_16;HistoryLength=86400")))))
- .hasValueSatisfying(scope -> assertThat(scope)
- .returns(86_400, org.greenbuttonalliance.espi.common.scope.EspiScope::historyLength)
- .returns(true, s -> s.containsFunctionBlock(16)));
- assertThat(resolver.espiScope(auth(Map.of("scope", "FB=4_5 openid")))).isPresent();
+ @DisplayName("espiScopes: every FB scope but FB=34_35; HistoryLength is the shortest stated; a bad FB scope throws")
+ void espiScopes() {
+ Authentication twoScopes = auth(Map.of("scope",
+ List.of("openid", "FB=4_5_16;HistoryLength=86400", "FB=4_5;HistoryLength=3600", "FB=34_35")));
+
+ assertThat(resolver.espiScopes(twoScopes))
+ .extracting(EspiScope::historyLength)
+ .containsExactly(86_400, 3_600);
+ assertThat(resolver.historyLengthSeconds(twoScopes)).contains(3_600L);
+ assertThat(resolver.historyLengthSeconds(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
assertThat(List.of(
- resolver.espiScope(auth(Map.of("scope", List.of("FB=34_35")))),
- resolver.espiScope(auth(Map.of("scope", List.of("FB=4_x")))),
- resolver.espiScope(auth(Map.of("active", true))),
- resolver.espiScope(null)))
+ resolver.espiScopes(auth(Map.of("scope", List.of("FB=34_35")))),
+ resolver.espiScopes(auth(Map.of("active", true))),
+ resolver.espiScopes(null)))
.allSatisfy(result -> assertThat(result).isEmpty());
+ assertThatThrownBy(() -> resolver.historyLengthSeconds(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x")))))
+ .isInstanceOf(IllegalArgumentException.class);
}
}
From 6c3ed738a49be1d865aee70b3c1710ed23ee3218 Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 19:38:44 -0500
Subject: [PATCH 4/9] feat(datacustodian): Batch/Subscription UsagePoints by
commodity Function 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
---
.../config/SecurityConfiguration.java | 5 ++
.../config/UsageFunctionBlockAuthorities.java | 27 ++++++++++
.../web/api/BatchSubscriptionController.java | 7 +--
.../web/api/SubscriptionFeedAssembler.java | 31 ++++++++---
.../api/BatchSubscriptionIntegrationTest.java | 52 +++++++++++++++++--
5 files changed, 110 insertions(+), 12 deletions(-)
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
index 0f6243cb..a60aad4a 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
@@ -192,6 +192,11 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http,
"/espi/1_1/resource/RetailCustomer/*/UsagePoint/*/ElectricPowerQualitySummary/**")
.access(powerQuality)
+ // --- Batch/Subscription (#279): FB_4, or admin. The feed holds only the UsagePoints whose
+ // service category a granted commodity FB covers, so FB_4 alone is an empty feed, not a 403. ---
+ .requestMatchers(HttpMethod.GET, "/espi/1_1/resource/Batch/Subscription/*")
+ .access(AuthorizationManagers.anyOf(admin, fb4))
+
// --- Usage data (GET, read-only) : FB_4 + commodity, or admin ---
.requestMatchers(HttpMethod.GET,
"/espi/1_1/resource/UsagePoint/**",
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
index 2e594802..efe8d81b 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
@@ -19,12 +19,15 @@
package org.greenbuttonalliance.espi.datacustodian.config;
+import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
import org.greenbuttonalliance.espi.common.scope.FunctionBlock;
import org.greenbuttonalliance.espi.common.scope.FunctionBlockCategory;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
+import java.util.EnumSet;
import java.util.List;
+import java.util.Set;
import java.util.stream.Stream;
/**
@@ -53,6 +56,30 @@ public final class UsageFunctionBlockAuthorities {
private UsageFunctionBlockAuthorities() {
}
+ /**
+ * The UsagePoint service categories the token's commodity Function Blocks grant, from each FB's service
+ * kind: FB_5 to FB_9 grant ELECTRICITY, FB_10 GAS, FB_11 WATER. A commodity FB without a service kind
+ * (FB_29, temperature: #283) grants no category. Interval metering (FB_4) alone grants none.
+ */
+ public static Set serviceCategories(Authentication authentication) {
+ Set categories = EnumSet.noneOf(ServiceCategory.class);
+ if (authentication == null) {
+ return categories;
+ }
+ for (GrantedAuthority granted : authentication.getAuthorities()) {
+ String name = granted.getAuthority();
+ if (name == null || !name.startsWith("FB_") || !COMMODITY.contains(name)) {
+ continue;
+ }
+ FunctionBlock.serviceKindOf(Integer.parseInt(name.substring(3)))
+ .flatMap(kind -> Stream.of(ServiceCategory.values())
+ .filter(category -> category.name().equals(kind.name()))
+ .findFirst())
+ .ifPresent(categories::add);
+ }
+ return categories;
+ }
+
/** Whether the authentication holds at least one of the authorities. */
public static boolean hasAny(Authentication authentication, List authorities) {
if (authentication == null) {
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
index a1264fe8..6a4941ec 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -55,9 +55,9 @@
*
* Access ({@link ScopeResolver#canReadSubscription}): the DataCustodian admin, or a customer access
* token for exactly this subscription. Anything else gets 403, whether or not the subscription exists. The
- * URL rule in {@code SecurityConfiguration} requires interval metering and a commodity Function Block first,
- * and the token's Function Blocks decide which summaries the feed holds
- * ({@link UsageFunctionBlockAuthorities}).
+ * URL rule in {@code SecurityConfiguration} requires interval metering (FB_4) first. The token's commodity
+ * Function Blocks decide which UsagePoints the feed holds (by service category; none with FB_4 alone), and its
+ * summary Function Blocks which summaries ({@link UsageFunctionBlockAuthorities}).
*/
@RestController
@RequestMapping("/espi/1_1/resource")
@@ -142,6 +142,7 @@ private Grants grants(Authentication authentication) {
throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Unreadable ESPI scope");
}
return new Grants(
+ UsageFunctionBlockAuthorities.serviceCategories(authentication),
UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.USAGE_SUMMARY),
UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.POWER_QUALITY),
historyLength);
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index 93759bac..d0b589ff 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -20,6 +20,7 @@
package org.greenbuttonalliance.espi.datacustodian.web.api;
import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
+import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
import org.greenbuttonalliance.espi.common.domain.common.IdentifiedObject;
import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
@@ -50,6 +51,7 @@
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.Comparator;
+import java.util.EnumSet;
import java.util.HashSet;
import java.util.List;
import java.util.Optional;
@@ -61,8 +63,12 @@
* Builds {@code Batch/Subscription/{subscriptionId}} (#279): one Atom feed with the energy usage data of a
* subscription. The caller has already checked who may read it ({@code ScopeResolver#canReadSubscription}).
*
- * Entries, in the order of certified feeds, for each UsagePoint the customer selected (UsagePoints and
- * MeterReadings by id, time-bounded resources by interval start):
+ * UsagePoints: those the customer selected whose {@code ServiceCategory} a granted commodity Function Block
+ * covers (FB_5 to FB_9 electricity, FB_10 gas, FB_11 water); a token with interval metering (FB_4) and no
+ * such FB gets none. Temperature (FB_29) is not yet defined (#283).
+ *
+ * Entries, in the order of certified feeds, for each of those UsagePoints (UsagePoints and MeterReadings
+ * by id, time-bounded resources by interval start):
*
* - the UsagePoint;
* - each MeterReading, its ReadingType (once in the feed, even if shared) and its IntervalBlocks;
@@ -95,11 +101,20 @@ public class SubscriptionFeedAssembler {
/** The default range when the request has neither {@code published-min} nor {@code published-max}. */
static final long DEFAULT_WINDOW_SECONDS = 24 * 60 * 60L;
- /** What the token grants, beyond reading the subscription at all. */
- public record Grants(boolean usageSummaries, boolean powerQualitySummaries, Long historyLengthSeconds) {
+ /**
+ * What the token grants, beyond reading the subscription at all: the UsagePoint service categories its
+ * commodity Function Blocks cover, the summaries, and the HistoryLength ceiling.
+ */
+ public record Grants(Set serviceCategories, boolean usageSummaries,
+ boolean powerQualitySummaries, Long historyLengthSeconds) {
+
+ public Grants {
+ serviceCategories = serviceCategories == null || serviceCategories.isEmpty()
+ ? Set.of() : Set.copyOf(serviceCategories);
+ }
public static Grants all() {
- return new Grants(true, true, null);
+ return new Grants(EnumSet.allOf(ServiceCategory.class), true, true, null);
}
}
@@ -166,7 +181,11 @@ private List entries(SubscriptionEntity subscription, String resource
Set localTimesInFeed = new HashSet<>();
List entries = new ArrayList<>();
- for (UsagePointEntity usagePoint : sorted(subscription.getUsagePoints(), BY_ID)) {
+ List usagePoints = sorted(subscription.getUsagePoints(), BY_ID).stream()
+ .filter(usagePoint -> usagePoint.getServiceCategory() != null
+ && grants.serviceCategories().contains(usagePoint.getServiceCategory()))
+ .toList();
+ for (UsagePointEntity usagePoint : usagePoints) {
String usagePointFeed = subscriptionHref + "/UsagePoint";
String usagePointHref = usagePointFeed + "/" + usagePoint.getId();
List summaries = !grants.usageSummaries() ? List.of()
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index e977c11c..f3e11a9a 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -103,6 +103,10 @@ class BatchSubscriptionIntegrationTest {
private static final UUID SHARED_POINT_1 = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f503");
private static final UUID SHARED_POINT_2 = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f504");
private static final UUID SHARED_LOCAL_TIME = UUID.fromString("ae8e1505-cd4f-5199-a4e4-61507c8d9e02");
+ private static final UUID MIXED_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a05");
+ private static final UUID ELECTRIC_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f505");
+ private static final UUID GAS_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f506");
+ private static final UUID WATER_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f507");
/** When the fixtures were made, in epoch seconds. */
private long now;
@@ -261,15 +265,45 @@ void unreadable_scope_is_refused() throws Exception {
.andExpect(status().isForbidden());
}
+ @Test
+ @DisplayName("UsagePoints by commodity FB: FB_5 electricity, FB_10 gas, FB_11 water; FB_4 alone is an empty feed")
+ void usage_points_need_their_commodity_function_block() throws Exception {
+ List usagePoints = new ArrayList<>();
+ for (UsagePointEntity usagePoint : List.of(
+ usagePoint(ELECTRIC_POINT, ServiceCategory.ELECTRICITY),
+ usagePoint(GAS_POINT, ServiceCategory.GAS),
+ usagePoint(WATER_POINT, ServiceCategory.WATER))) {
+ usagePoints.add(usagePointRepository.save(usagePoint));
+ }
+ subscriptionRepository.saveAndFlush(subscription(MIXED_SUBSCRIPTION, usagePoints));
+
+ String electricity = fetch(MIXED_SUBSCRIPTION, token(MIXED_SUBSCRIPTION, "FB=1_3_4_5", "FB_4", "FB_5"));
+ String gasAndWater = fetch(MIXED_SUBSCRIPTION,
+ token(MIXED_SUBSCRIPTION, "FB=1_3_4_10_11", "FB_4", "FB_10", "FB_11"));
+ String intervalOnly = fetch(MIXED_SUBSCRIPTION, token(MIXED_SUBSCRIPTION, "FB=1_3_4", "FB_4"));
+
+ assertThat(electricity).contains(ELECTRIC_POINT.toString())
+ .doesNotContain(GAS_POINT.toString(), WATER_POINT.toString());
+ assertThat(gasAndWater).contains(GAS_POINT.toString(), WATER_POINT.toString())
+ .doesNotContain(ELECTRIC_POINT.toString());
+ assertThat(intervalOnly)
+ .contains("href=\"" + BASE + "/Batch/Subscription/" + MIXED_SUBSCRIPTION + "\" type=\"espi-feed/Subscription\"")
+ .doesNotContain(" usagePoints = new ArrayList<>();
for (UUID id : List.of(SHARED_POINT_1, SHARED_POINT_2)) {
- UsagePointEntity usagePoint = new UsagePointEntity();
- usagePoint.setId(id);
- usagePoint.setServiceCategory(ServiceCategory.ELECTRICITY);
+ UsagePointEntity usagePoint = usagePoint(id, ServiceCategory.ELECTRICITY);
usagePoint.setLocalTimeParameters(shared);
usagePoints.add(usagePointRepository.save(usagePoint));
}
@@ -366,6 +400,11 @@ private static void assertValid(String xml) {
private static RequestPostProcessor customer(UUID subscriptionId, String scope, String... extraFbs) {
String[] fbs = Arrays.copyOf(ENERGY_FBS, ENERGY_FBS.length + extraFbs.length);
System.arraycopy(extraFbs, 0, fbs, ENERGY_FBS.length, extraFbs.length);
+ return token(subscriptionId, scope, fbs);
+ }
+
+ /** A customer access token for the subscription with exactly these FB authorities. */
+ private static RequestPostProcessor token(UUID subscriptionId, String scope, String... fbs) {
return opaqueToken()
.attributes(attributes -> {
attributes.put("resourceURI", BASE + "/Batch/Subscription/" + subscriptionId);
@@ -443,6 +482,13 @@ private static UsagePointEntity usagePointA(long now) {
return usagePoint;
}
+ private static UsagePointEntity usagePoint(UUID id, ServiceCategory serviceCategory) {
+ UsagePointEntity usagePoint = new UsagePointEntity();
+ usagePoint.setId(id);
+ usagePoint.setServiceCategory(serviceCategory);
+ return usagePoint;
+ }
+
private static TimeConfigurationEntity localTime(UUID id) {
TimeConfigurationEntity localTime = new TimeConfigurationEntity();
localTime.setId(id);
From 6782c1914cbe64e73a9f63dcac8410d380b2fb2e Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 20:12:20 -0500
Subject: [PATCH 5/9] fix(datacustodian): Batch/Subscription requires FB_4 plus
an electricity, 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
---
.../config/SecurityConfiguration.java | 8 +++++---
.../config/UsageFunctionBlockAuthorities.java | 12 +++++++++++-
.../web/api/BatchSubscriptionController.java | 6 +++---
.../web/api/SubscriptionFeedAssembler.java | 4 ++--
.../api/BatchSubscriptionIntegrationTest.java | 19 ++++++++++---------
5 files changed, 31 insertions(+), 18 deletions(-)
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
index a60aad4a..367c760b 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
@@ -192,10 +192,12 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http,
"/espi/1_1/resource/RetailCustomer/*/UsagePoint/*/ElectricPowerQualitySummary/**")
.access(powerQuality)
- // --- Batch/Subscription (#279): FB_4, or admin. The feed holds only the UsagePoints whose
- // service category a granted commodity FB covers, so FB_4 alone is an empty feed, not a 403. ---
+ // --- Batch/Subscription (#279): FB_4 + an electricity, gas or water FB (FB_5-FB_11), or admin.
+ // The feed holds only the UsagePoints whose service category a granted FB covers. ---
.requestMatchers(HttpMethod.GET, "/espi/1_1/resource/Batch/Subscription/*")
- .access(AuthorizationManagers.anyOf(admin, fb4))
+ .access(AuthorizationManagers.anyOf(admin, AuthorizationManagers.allOf(fb4,
+ AuthorityAuthorizationManager.hasAnyAuthority(
+ UsageFunctionBlockAuthorities.SERVICE_COMMODITY.toArray(String[]::new)))))
// --- Usage data (GET, read-only) : FB_4 + commodity, or admin ---
.requestMatchers(HttpMethod.GET,
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
index efe8d81b..5f4ac21e 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
@@ -53,6 +53,16 @@ public final class UsageFunctionBlockAuthorities {
.map(fb -> "FB_" + fb.getId())
.toList();
+ /**
+ * The commodity FBs that cover a UsagePoint service category (FB_5 to FB_9 electricity, FB_10 gas, FB_11
+ * water): one is needed with {@link #INTERVAL_METERING} for {@code Batch/Subscription}. FB_29 (temperature,
+ * no service kind yet: #283) is not one of them.
+ */
+ public static final List SERVICE_COMMODITY = Stream.of(FunctionBlock.values())
+ .filter(fb -> fb.getCategory() == FunctionBlockCategory.COMMODITY && fb.getServiceKind().isPresent())
+ .map(fb -> "FB_" + fb.getId())
+ .toList();
+
private UsageFunctionBlockAuthorities() {
}
@@ -68,7 +78,7 @@ public static Set serviceCategories(Authentication authenticati
}
for (GrantedAuthority granted : authentication.getAuthorities()) {
String name = granted.getAuthority();
- if (name == null || !name.startsWith("FB_") || !COMMODITY.contains(name)) {
+ if (name == null || !SERVICE_COMMODITY.contains(name)) {
continue;
}
FunctionBlock.serviceKindOf(Integer.parseInt(name.substring(3)))
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
index 6a4941ec..cc2b1928 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -55,9 +55,9 @@
*
* Access ({@link ScopeResolver#canReadSubscription}): the DataCustodian admin, or a customer access
* token for exactly this subscription. Anything else gets 403, whether or not the subscription exists. The
- * URL rule in {@code SecurityConfiguration} requires interval metering (FB_4) first. The token's commodity
- * Function Blocks decide which UsagePoints the feed holds (by service category; none with FB_4 alone), and its
- * summary Function Blocks which summaries ({@link UsageFunctionBlockAuthorities}).
+ * URL rule in {@code SecurityConfiguration} requires interval metering (FB_4) and an electricity, gas or water
+ * Function Block (FB_5 to FB_11) first. Those commodity Function Blocks decide which UsagePoints the feed holds
+ * (by service category), and the summary Function Blocks which summaries ({@link UsageFunctionBlockAuthorities}).
*/
@RestController
@RequestMapping("/espi/1_1/resource")
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index d0b589ff..670b1c00 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -64,8 +64,8 @@
* subscription. The caller has already checked who may read it ({@code ScopeResolver#canReadSubscription}).
*
* UsagePoints: those the customer selected whose {@code ServiceCategory} a granted commodity Function Block
- * covers (FB_5 to FB_9 electricity, FB_10 gas, FB_11 water); a token with interval metering (FB_4) and no
- * such FB gets none. Temperature (FB_29) is not yet defined (#283).
+ * covers (FB_5 to FB_9 electricity, FB_10 gas, FB_11 water; the URL rule requires one of them with FB_4).
+ * Temperature (FB_29) is not yet defined (#283).
*
* Entries, in the order of certified feeds, for each of those UsagePoints (UsagePoints and MeterReadings
* by id, time-bounded resources by interval start):
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index f3e11a9a..f4970081 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -266,7 +266,7 @@ void unreadable_scope_is_refused() throws Exception {
}
@Test
- @DisplayName("UsagePoints by commodity FB: FB_5 electricity, FB_10 gas, FB_11 water; FB_4 alone is an empty feed")
+ @DisplayName("UsagePoints by commodity FB: FB_5 electricity, FB_10 gas, FB_11 water; FB_4 needs one of FB_5-FB_11")
void usage_points_need_their_commodity_function_block() throws Exception {
List usagePoints = new ArrayList<>();
for (UsagePointEntity usagePoint : List.of(
@@ -280,19 +280,20 @@ void usage_points_need_their_commodity_function_block() throws Exception {
String electricity = fetch(MIXED_SUBSCRIPTION, token(MIXED_SUBSCRIPTION, "FB=1_3_4_5", "FB_4", "FB_5"));
String gasAndWater = fetch(MIXED_SUBSCRIPTION,
token(MIXED_SUBSCRIPTION, "FB=1_3_4_10_11", "FB_4", "FB_10", "FB_11"));
- String intervalOnly = fetch(MIXED_SUBSCRIPTION, token(MIXED_SUBSCRIPTION, "FB=1_3_4", "FB_4"));
assertThat(electricity).contains(ELECTRIC_POINT.toString())
.doesNotContain(GAS_POINT.toString(), WATER_POINT.toString());
assertThat(gasAndWater).contains(GAS_POINT.toString(), WATER_POINT.toString())
.doesNotContain(ELECTRIC_POINT.toString());
- assertThat(intervalOnly)
- .contains("href=\"" + BASE + "/Batch/Subscription/" + MIXED_SUBSCRIPTION + "\" type=\"espi-feed/Subscription\"")
- .doesNotContain("
Date: Wed, 18 Nov 2026 21:27:06 -0500
Subject: [PATCH 6/9] fix(datacustodian): HistoryLength in months, second #282
review fixes (#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
---
.../domain/usage/enums/ServiceKind.java | 23 +++++++
.../config/UsageFunctionBlockAuthorities.java | 26 ++++----
.../web/api/BatchSubscriptionController.java | 16 +++--
.../web/api/SubscriptionFeedAssembler.java | 38 ++++++------
.../web/api/scope/ScopeResolver.java | 13 ++--
.../web/authorize/AuthorizeScreenService.java | 8 +--
.../api/BatchSubscriptionIntegrationTest.java | 61 ++++++++++++++-----
.../web/api/scope/ScopeResolverTest.java | 18 +++---
8 files changed, 131 insertions(+), 72 deletions(-)
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java
index dec2f3d9..02d3c7f9 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/domain/usage/enums/ServiceKind.java
@@ -16,6 +16,10 @@
package org.greenbuttonalliance.espi.common.domain.usage.enums;
+import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
+
+import java.util.Optional;
+
import jakarta.xml.bind.annotation.XmlEnum;
import jakarta.xml.bind.annotation.XmlEnumValue;
import jakarta.xml.bind.annotation.XmlType;
@@ -118,4 +122,23 @@ public static ServiceKind fromValue(int value) {
}
throw new IllegalArgumentException("Invalid ServiceKind value: " + value);
}
+
+ /**
+ * The ServiceKind of a UsagePoint's {@link ServiceCategory}, matched by espi.xsd code (both enums carry the
+ * ServiceKind codes 0-9; their constant names differ, e.g. TV_LICENSE / TV_LICENCE). The one mapping used by
+ * the consent screen and the Batch/Subscription feed.
+ *
+ * @return the kind, or empty for null or a code with no ServiceKind
+ */
+ public static Optional of(ServiceCategory category) {
+ if (category == null || category.getValue() == null) {
+ return Optional.empty();
+ }
+ for (ServiceKind kind : values()) {
+ if (kind.value == category.getValue()) {
+ return Optional.of(kind);
+ }
+ }
+ return Optional.empty();
+ }
}
\ No newline at end of file
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
index 5f4ac21e..322013cf 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
@@ -19,7 +19,7 @@
package org.greenbuttonalliance.espi.datacustodian.config;
-import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
+import org.greenbuttonalliance.espi.common.domain.usage.enums.ServiceKind;
import org.greenbuttonalliance.espi.common.scope.FunctionBlock;
import org.greenbuttonalliance.espi.common.scope.FunctionBlockCategory;
import org.springframework.security.core.Authentication;
@@ -67,27 +67,23 @@ private UsageFunctionBlockAuthorities() {
}
/**
- * The UsagePoint service categories the token's commodity Function Blocks grant, from each FB's service
- * kind: FB_5 to FB_9 grant ELECTRICITY, FB_10 GAS, FB_11 WATER. A commodity FB without a service kind
- * (FB_29, temperature: #283) grants no category. Interval metering (FB_4) alone grants none.
+ * The UsagePoint service kinds the token's commodity Function Blocks grant, from each FB's service kind:
+ * FB_5 to FB_9 grant ELECTRICITY, FB_10 GAS, FB_11 WATER. A commodity FB without a service kind (FB_29,
+ * temperature: #283) grants none, nor does interval metering (FB_4) alone. A UsagePoint's kind is
+ * {@link ServiceKind#of}, the mapping the consent screen uses.
*/
- public static Set serviceCategories(Authentication authentication) {
- Set categories = EnumSet.noneOf(ServiceCategory.class);
+ public static Set serviceKinds(Authentication authentication) {
+ Set kinds = EnumSet.noneOf(ServiceKind.class);
if (authentication == null) {
- return categories;
+ return kinds;
}
for (GrantedAuthority granted : authentication.getAuthorities()) {
String name = granted.getAuthority();
- if (name == null || !SERVICE_COMMODITY.contains(name)) {
- continue;
+ if (name != null && SERVICE_COMMODITY.contains(name)) {
+ FunctionBlock.serviceKindOf(Integer.parseInt(name.substring(3))).ifPresent(kinds::add);
}
- FunctionBlock.serviceKindOf(Integer.parseInt(name.substring(3)))
- .flatMap(kind -> Stream.of(ServiceCategory.values())
- .filter(category -> category.name().equals(kind.name()))
- .findFirst())
- .ifPresent(categories::add);
}
- return categories;
+ return kinds;
}
/** Whether the authentication holds at least one of the authorities. */
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
index cc2b1928..5199be56 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -87,7 +87,8 @@ public BatchSubscriptionController(ScopeResolver scopeResolver, SubscriptionFeed
+ " IntervalBlocks, summaries and LocalTimeParameters, as granted by the token's scope",
responses = {
@ApiResponse(responseCode = "200", description = "The subscription's feed"),
- @ApiResponse(responseCode = "400", description = "A query parameter is not an xs:dateTime"),
+ @ApiResponse(responseCode = "400",
+ description = "A query parameter is not an xs:dateTime, or a -min is after its -max"),
@ApiResponse(responseCode = "401", description = "Unauthorized"),
@ApiResponse(responseCode = "403", description = "Not this token's subscription"),
@ApiResponse(responseCode = "404", description = "No such subscription (DataCustodian admin only)")
@@ -114,6 +115,9 @@ public ResponseEntity getSubscription(
if (!scopeResolver.canReadSubscription(authentication, subscriptionId)) {
throw new ResponseStatusException(HttpStatus.FORBIDDEN);
}
+ if (reversed(publishedMin, publishedMax) || reversed(updatedMin, updatedMax)) {
+ throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "A -min query parameter is after its -max");
+ }
Range range = new Range(instant(publishedMin), instant(publishedMax), instant(updatedMin), instant(updatedMax));
String feedHref = ServletUriComponentsBuilder.fromCurrentRequestUri().toUriString();
String resourceBase = feedHref.substring(0, feedHref.indexOf(BATCH_SUBSCRIPTION));
@@ -135,19 +139,23 @@ private Grants grants(Authentication authentication) {
if (scopeResolver.isAdmin(authentication)) {
return Grants.all();
}
- Long historyLength;
+ Integer historyLength;
try {
- historyLength = scopeResolver.historyLengthSeconds(authentication).orElse(null);
+ historyLength = scopeResolver.historyLengthMonths(authentication).orElse(null);
} catch (IllegalArgumentException ex) {
throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Unreadable ESPI scope");
}
return new Grants(
- UsageFunctionBlockAuthorities.serviceCategories(authentication),
+ UsageFunctionBlockAuthorities.serviceKinds(authentication),
UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.USAGE_SUMMARY),
UsageFunctionBlockAuthorities.hasAny(authentication, UsageFunctionBlockAuthorities.POWER_QUALITY),
historyLength);
}
+ private static boolean reversed(OffsetDateTime min, OffsetDateTime max) {
+ return min != null && max != null && min.isAfter(max);
+ }
+
private static Instant instant(OffsetDateTime time) {
return time == null ? null : time.toInstant();
}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index 670b1c00..9b59f9ad 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -20,7 +20,7 @@
package org.greenbuttonalliance.espi.datacustodian.web.api;
import org.greenbuttonalliance.espi.common.domain.common.DateTimeInterval;
-import org.greenbuttonalliance.espi.common.domain.common.ServiceCategory;
+import org.greenbuttonalliance.espi.common.domain.usage.enums.ServiceKind;
import org.greenbuttonalliance.espi.common.domain.common.IdentifiedObject;
import org.greenbuttonalliance.espi.common.domain.usage.ElectricPowerQualitySummaryEntity;
import org.greenbuttonalliance.espi.common.domain.usage.IntervalBlockEntity;
@@ -51,7 +51,6 @@
import java.time.ZoneOffset;
import java.util.ArrayList;
import java.util.Comparator;
-import java.util.EnumSet;
import java.util.HashSet;
import java.util.List;
import java.util.Optional;
@@ -88,9 +87,10 @@
* recent UsageSummary and its most recent ElectricPowerQualitySummary (summary intervals rarely line up
* with a 24-hour window);
* - {@code updated-min}/{@code updated-max} select by {@code atom:updated};
- * - {@code HistoryLength} (REQ.21: "the amount of historical information available from the Data
- * Custodian in seconds") is a ceiling, not a selection: nothing that ended before now minus that length
- * is returned, whatever the range asks for.
+ * - {@code HistoryLength}, in months (the GBA reading, as in the Authorization Server's
+ * {@code HistoryLength=13}; REQ.21's definition text says seconds, see the HistoryLength issue), is a
+ * ceiling, not a selection: nothing that ended before now minus that many calendar months (UTC) is
+ * returned, whatever the range asks for.
*
* A resource without an interval is kept: there is nothing to measure it against. {@code BlockDuration}
* describes the blocks and selects nothing.
@@ -102,19 +102,21 @@ public class SubscriptionFeedAssembler {
static final long DEFAULT_WINDOW_SECONDS = 24 * 60 * 60L;
/**
- * What the token grants, beyond reading the subscription at all: the UsagePoint service categories its
- * commodity Function Blocks cover, the summaries, and the HistoryLength ceiling.
+ * What the token grants, beyond reading the subscription at all: the UsagePoint service kinds its
+ * commodity Function Blocks cover, the summaries, and the HistoryLength ceiling in months.
+ *
+ * @param serviceKinds null for every UsagePoint (the admin)
*/
- public record Grants(Set serviceCategories, boolean usageSummaries,
- boolean powerQualitySummaries, Long historyLengthSeconds) {
+ public record Grants(Set serviceKinds, boolean usageSummaries,
+ boolean powerQualitySummaries, Integer historyLengthMonths) {
- public Grants {
- serviceCategories = serviceCategories == null || serviceCategories.isEmpty()
- ? Set.of() : Set.copyOf(serviceCategories);
+ public static Grants all() {
+ return new Grants(null, true, true, null);
}
- public static Grants all() {
- return new Grants(EnumSet.allOf(ServiceCategory.class), true, true, null);
+ boolean covers(UsagePointEntity usagePoint) {
+ return serviceKinds == null
+ || ServiceKind.of(usagePoint.getServiceCategory()).map(serviceKinds::contains).orElse(false);
}
}
@@ -182,8 +184,7 @@ private List entries(SubscriptionEntity subscription, String resource
List entries = new ArrayList<>();
List usagePoints = sorted(subscription.getUsagePoints(), BY_ID).stream()
- .filter(usagePoint -> usagePoint.getServiceCategory() != null
- && grants.serviceCategories().contains(usagePoint.getServiceCategory()))
+ .filter(grants::covers)
.toList();
for (UsagePointEntity usagePoint : usagePoints) {
String usagePointFeed = subscriptionHref + "/UsagePoint";
@@ -274,14 +275,15 @@ private static LinkDto related(String href, String type) {
/**
* Which time-bounded resources a request gets, in epoch seconds. {@code from}/{@code to} bound the overlap
- * (null = open); {@code ceiling} is now minus {@code HistoryLength} (null = no limit).
+ * (null = open); {@code ceiling} is now minus {@code HistoryLength} months (null = no limit).
*/
private record Selection(Long from, Long to, Long ceiling, Long updatedMin, Long updatedMax,
boolean defaultWindow) {
static Selection of(Range range, Grants grants, Instant now) {
long nowSeconds = now.getEpochSecond();
- Long ceiling = grants.historyLengthSeconds() == null ? null : nowSeconds - grants.historyLengthSeconds();
+ Long ceiling = grants.historyLengthMonths() == null ? null
+ : now.atOffset(ZoneOffset.UTC).minusMonths(grants.historyLengthMonths()).toEpochSecond();
boolean defaultWindow = range.publishedMin() == null && range.publishedMax() == null;
Long from = defaultWindow ? Long.valueOf(nowSeconds - DEFAULT_WINDOW_SECONDS) : seconds(range.publishedMin());
return new Selection(from, defaultWindow ? null : seconds(range.publishedMax()), ceiling,
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
index 6f23d4c3..22eb4aa1 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
@@ -160,7 +160,7 @@ public List espiScopes(Authentication authentication) {
for (Object value : scopes) {
String text = value == null ? "" : value.toString().trim();
if (text.regionMatches(true, 0, "FB=", 0, 3)
- && !EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN_SCOPE.equals(text)) {
+ && !EspiScopeOpaqueTokenIntrospector.CLIENT_ACCESS_TOKEN_SCOPE.equalsIgnoreCase(text)) {
parsed.add(EspiScope.parse(text));
}
}
@@ -168,17 +168,18 @@ public List espiScopes(Authentication authentication) {
}
/**
- * The token's {@code HistoryLength} in seconds: the shortest among its FB scopes, or empty if none states
- * one.
+ * The {@code HistoryLength} of the token's usage-data scopes, in months: the shortest among its FB scopes
+ * that grant interval metering (FB_4), or empty if none states one. A customer-data scope (e.g.
+ * {@code FB=51_53_54;HistoryLength=...}) does not limit usage data.
*
* @throws IllegalArgumentException if an FB scope does not parse (see {@link #espiScopes})
*/
- public Optional historyLengthSeconds(Authentication authentication) {
+ public Optional historyLengthMonths(Authentication authentication) {
return espiScopes(authentication).stream()
+ .filter(scope -> scope.containsFunctionBlock(4))
.map(EspiScope::historyLength)
.filter(Objects::nonNull)
- .map(Integer::longValue)
- .min(Long::compare);
+ .min(Integer::compare);
}
/** Whether the caller holds the DataCustodian admin authority. */
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java
index 3dfe0b83..86b80de2 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/authorize/AuthorizeScreenService.java
@@ -314,13 +314,7 @@ private static String rebuildScope(EspiScope original, Set keptFbs) {
}
private static ServiceKind toServiceKind(ServiceCategory category) {
- if (category == null) return null;
- try {
- return ServiceKind.valueOf(category.name());
- }
- catch (IllegalArgumentException e) {
- return null;
- }
+ return ServiceKind.of(category).orElse(null);
}
private static List sortedKinds(Set kinds) {
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index f4970081..958a30f4 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -107,6 +107,9 @@ class BatchSubscriptionIntegrationTest {
private static final UUID ELECTRIC_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f505");
private static final UUID GAS_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f506");
private static final UUID WATER_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f507");
+ private static final UUID LATEST_SUBSCRIPTION = UUID.fromString("3c9d0e6b-6a56-5f11-9a3e-0d1c3b1c2a06");
+ private static final UUID LATEST_POINT = UUID.fromString("48c2a019-5598-5e16-b0f9-49e4ff27f508");
+ private static final UUID LATEST_QUALITY = UUID.fromString("9d7d04f4-bc3e-5088-93d3-504f6b7c8d03");
/** When the fixtures were made, in epoch seconds. */
private long now;
@@ -239,29 +242,59 @@ void summaries_need_their_function_blocks() throws Exception {
}
@Test
- @DisplayName("HistoryLength is a ceiling: nothing that ended before now minus it, whatever the range asks for")
+ @DisplayName("HistoryLength (months) is a ceiling: nothing that ended before now minus it, whatever the range asks for")
void history_length_is_a_ceiling() throws Exception {
- String wide = fetch(SUBSCRIPTION_A,
- customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (7 * DAY), "FB_16", "FB_17"),
+ String oneMonth = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=1", "FB_16", "FB_17"),
+ "published-min", ago(100 * DAY));
+ String threeMonths = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=3", "FB_16", "FB_17"),
"published-min", ago(100 * DAY));
- // By default the latest power quality summary is added, but not past the ceiling: it ended 5 days ago.
- String latest = fetch(SUBSCRIPTION_A,
- customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (2 * DAY), "FB_16", "FB_17"));
- assertThat(wide)
+ // The old block ended 39 days ago, the old summaries 60 days ago.
+ assertThat(oneMonth)
.contains(RECENT_BLOCK.toString(), USAGE_SUMMARY_A.toString(), QUALITY_SUMMARY_A.toString())
.doesNotContain(OLD_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
- assertThat(latest)
- .contains(RECENT_BLOCK.toString(), USAGE_SUMMARY_A.toString())
- .doesNotContain(QUALITY_SUMMARY_A.toString(), OLD_QUALITY_SUMMARY.toString());
- assertValid(wide);
+ assertThat(threeMonths)
+ .contains(OLD_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
+ assertValid(oneMonth);
+ }
+
+ @Test
+ @DisplayName("by default the latest summary is added, but never past the HistoryLength ceiling")
+ void latest_summary_respects_the_ceiling() throws Exception {
+ UsagePointEntity usagePoint = usagePoint(LATEST_POINT, ServiceCategory.ELECTRICITY);
+ usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(LATEST_QUALITY, usagePoint, now - 90 * DAY));
+ subscriptionRepository.saveAndFlush(
+ subscription(LATEST_SUBSCRIPTION, List.of(usagePointRepository.save(usagePoint))));
+
+ // Its only power quality summary ended 60 days ago.
+ String oneMonth = fetch(LATEST_SUBSCRIPTION,
+ customer(LATEST_SUBSCRIPTION, "FB=1_3_4_5_17;HistoryLength=1", "FB_17"));
+ String threeMonths = fetch(LATEST_SUBSCRIPTION,
+ customer(LATEST_SUBSCRIPTION, "FB=1_3_4_5_17;HistoryLength=3", "FB_17"));
+
+ assertThat(oneMonth).contains(LATEST_POINT.toString()).doesNotContain(LATEST_QUALITY.toString());
+ assertThat(threeMonths).contains(LATEST_QUALITY.toString());
+ }
+
+ @Test
+ @DisplayName("a -min after its -max is a 400")
+ void reversed_range_is_bad_request() throws Exception {
+ for (String[] range : List.of(new String[]{"published-min", ago(DAY), "published-max", ago(2 * DAY)},
+ new String[]{"updated-min", ago(DAY), "updated-max", ago(2 * DAY)})) {
+ mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A)
+ .param(range[0], range[1]).param(range[2], range[3])
+ .with(customer(SUBSCRIPTION_A, "FB=1_3_4_5")))
+ .andExpect(status().isBadRequest());
+ }
}
@Test
@DisplayName("an FB scope that does not parse is refused, not read as 'no HistoryLength'")
void unreadable_scope_is_refused() throws Exception {
mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A)
- .with(customer(SUBSCRIPTION_A, "FB=4_x;HistoryLength=86400")))
+ .with(customer(SUBSCRIPTION_A, "FB=4_x;HistoryLength=13")))
.andExpect(status().isForbidden());
}
@@ -446,7 +479,7 @@ private SubscriptionEntity subscription(UUID id, List usagePoi
return subscription;
}
- /** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 30 days ago; one
+ /** One UsagePoint with every child kind; one IntervalBlock from yesterday, one from 40 days ago; one
* UsageSummary ending now and one ElectricPowerQualitySummary ending 5 days ago, and one of each ending
* 60 days ago. Each collection gets its newer item first, so the feed's order comes from sorting. */
private static UsagePointEntity usagePointA(long now) {
@@ -473,7 +506,7 @@ private static UsagePointEntity usagePointA(long now) {
meterReading.setUsagePoint(usagePoint);
meterReading.setReadingType(readingType);
meterReading.getIntervalBlocks().add(block(RECENT_BLOCK, meterReading, now - DAY));
- meterReading.getIntervalBlocks().add(block(OLD_BLOCK, meterReading, now - 30 * DAY));
+ meterReading.getIntervalBlocks().add(block(OLD_BLOCK, meterReading, now - 40 * DAY));
usagePoint.getMeterReadings().add(meterReading);
usagePoint.getUsageSummaries().add(usageSummary(USAGE_SUMMARY_A, usagePoint, now - 30 * DAY, now));
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
index db65cd7a..e6265a76 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
@@ -161,22 +161,24 @@ void canReadSubscription() {
}
@Test
- @DisplayName("espiScopes: every FB scope but FB=34_35; HistoryLength is the shortest stated; a bad FB scope throws")
+ @DisplayName("espiScopes: every FB scope but FB=34_35 (any case); HistoryLength (months) is the shortest usage scope's; a bad FB scope throws")
void espiScopes() {
- Authentication twoScopes = auth(Map.of("scope",
- List.of("openid", "FB=4_5_16;HistoryLength=86400", "FB=4_5;HistoryLength=3600", "FB=34_35")));
+ Authentication scopes = auth(Map.of("scope", List.of("openid", "FB=4_5_16;HistoryLength=13",
+ "FB=4_5;HistoryLength=7", "FB=51_53_54;HistoryLength=1", "fb=34_35")));
- assertThat(resolver.espiScopes(twoScopes))
+ assertThat(resolver.espiScopes(scopes))
.extracting(EspiScope::historyLength)
- .containsExactly(86_400, 3_600);
- assertThat(resolver.historyLengthSeconds(twoScopes)).contains(3_600L);
- assertThat(resolver.historyLengthSeconds(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
+ .containsExactly(13, 7, 1);
+ // The customer-data scope's HistoryLength=1 does not limit usage data.
+ assertThat(resolver.historyLengthMonths(scopes)).contains(7);
+ assertThat(resolver.historyLengthMonths(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
assertThat(List.of(
resolver.espiScopes(auth(Map.of("scope", List.of("FB=34_35")))),
+ resolver.espiScopes(auth(Map.of("scope", List.of("fb=34_35")))),
resolver.espiScopes(auth(Map.of("active", true))),
resolver.espiScopes(null)))
.allSatisfy(result -> assertThat(result).isEmpty());
- assertThatThrownBy(() -> resolver.historyLengthSeconds(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x")))))
+ assertThatThrownBy(() -> resolver.historyLengthMonths(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x")))))
.isInstanceOf(IllegalArgumentException.class);
}
}
From 90eecd3d7e96353cf922937942ba39eddaac80e3 Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 21:39:53 -0500
Subject: [PATCH 7/9] fix(datacustodian): HistoryLength from every usage-data
scope, not only 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
---
.../config/UsageFunctionBlockAuthorities.java | 9 +++++++++
.../espi/datacustodian/web/api/scope/ScopeResolver.java | 9 ++++++---
.../datacustodian/web/api/scope/ScopeResolverTest.java | 5 ++++-
3 files changed, 19 insertions(+), 4 deletions(-)
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
index 322013cf..8a79e535 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java
@@ -63,6 +63,15 @@ public final class UsageFunctionBlockAuthorities {
.map(fb -> "FB_" + fb.getId())
.toList();
+ /**
+ * Every usage-data FB: interval metering, the commodities, the usage summaries and power quality. A scope
+ * with any of them is a usage scope whose {@code HistoryLength} limits usage data.
+ */
+ public static final List USAGE_DATA = Stream.of(
+ List.of(INTERVAL_METERING), COMMODITY, USAGE_SUMMARY, POWER_QUALITY)
+ .flatMap(List::stream)
+ .toList();
+
private UsageFunctionBlockAuthorities() {
}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
index 22eb4aa1..a524b72b 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
@@ -22,6 +22,7 @@
import org.greenbuttonalliance.espi.common.scope.EspiScope;
import org.greenbuttonalliance.espi.common.uri.EspiBatchUri;
import org.greenbuttonalliance.espi.datacustodian.config.EspiScopeOpaqueTokenIntrospector;
+import org.greenbuttonalliance.espi.datacustodian.config.UsageFunctionBlockAuthorities;
import org.springframework.security.core.Authentication;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.oauth2.core.OAuth2AuthenticatedPrincipal;
@@ -169,14 +170,16 @@ public List espiScopes(Authentication authentication) {
/**
* The {@code HistoryLength} of the token's usage-data scopes, in months: the shortest among its FB scopes
- * that grant interval metering (FB_4), or empty if none states one. A customer-data scope (e.g.
- * {@code FB=51_53_54;HistoryLength=...}) does not limit usage data.
+ * that grant any usage-data Function Block (interval metering, a commodity, a usage summary or power
+ * quality), or empty if none states one. Only a scope with no usage-data FB, such as a customer-data scope
+ * ({@code FB=51_53_54;HistoryLength=...}), is left out: it does not limit usage data.
*
* @throws IllegalArgumentException if an FB scope does not parse (see {@link #espiScopes})
*/
public Optional historyLengthMonths(Authentication authentication) {
return espiScopes(authentication).stream()
- .filter(scope -> scope.containsFunctionBlock(4))
+ .filter(scope -> scope.functionBlocks().stream()
+ .anyMatch(fb -> UsageFunctionBlockAuthorities.USAGE_DATA.contains("FB_" + fb)))
.map(EspiScope::historyLength)
.filter(Objects::nonNull)
.min(Integer::compare);
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
index e6265a76..4419b6b9 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
@@ -169,8 +169,11 @@ void espiScopes() {
assertThat(resolver.espiScopes(scopes))
.extracting(EspiScope::historyLength)
.containsExactly(13, 7, 1);
- // The customer-data scope's HistoryLength=1 does not limit usage data.
+ // The customer-data scope's HistoryLength=1 does not limit usage data...
assertThat(resolver.historyLengthMonths(scopes)).contains(7);
+ // ...but a summary-only scope without FB_4 does.
+ assertThat(resolver.historyLengthMonths(auth(Map.of("scope",
+ List.of("FB=4_5;HistoryLength=13", "FB=16_17;HistoryLength=1"))))).contains(1);
assertThat(resolver.historyLengthMonths(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
assertThat(List.of(
resolver.espiScopes(auth(Map.of("scope", List.of("FB=34_35")))),
From 237dbea3f0f757a409da63a979969b587e7d7a23 Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 22:40:02 -0500
Subject: [PATCH 8/9] fix(datacustodian): HistoryLength back to seconds, per
REQ.21.6.1.2.1 (#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
---
.../web/api/BatchSubscriptionController.java | 4 +--
.../web/api/SubscriptionFeedAssembler.java | 16 +++++------
.../web/api/scope/ScopeResolver.java | 8 ++++--
.../api/BatchSubscriptionIntegrationTest.java | 28 +++++++++----------
.../web/api/scope/ScopeResolverTest.java | 20 ++++++-------
5 files changed, 38 insertions(+), 38 deletions(-)
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
index 5199be56..e7ff0639 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -139,9 +139,9 @@ private Grants grants(Authentication authentication) {
if (scopeResolver.isAdmin(authentication)) {
return Grants.all();
}
- Integer historyLength;
+ Long historyLength;
try {
- historyLength = scopeResolver.historyLengthMonths(authentication).orElse(null);
+ historyLength = scopeResolver.historyLengthSeconds(authentication).orElse(null);
} catch (IllegalArgumentException ex) {
throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Unreadable ESPI scope");
}
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index 9b59f9ad..63669778 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -87,10 +87,9 @@
* recent UsageSummary and its most recent ElectricPowerQualitySummary (summary intervals rarely line up
* with a 24-hour window);
* - {@code updated-min}/{@code updated-max} select by {@code atom:updated};
- * - {@code HistoryLength}, in months (the GBA reading, as in the Authorization Server's
- * {@code HistoryLength=13}; REQ.21's definition text says seconds, see the HistoryLength issue), is a
- * ceiling, not a selection: nothing that ended before now minus that many calendar months (UTC) is
- * returned, whatever the range asks for.
+ * - {@code HistoryLength} (REQ.21.6.1.2.1: "The amount of historical information available from the Data
+ * Custodian in seconds") is a ceiling, not a selection: nothing that ended before now minus that many
+ * seconds is returned, whatever the range asks for.
*
* A resource without an interval is kept: there is nothing to measure it against. {@code BlockDuration}
* describes the blocks and selects nothing.
@@ -103,12 +102,12 @@ public class SubscriptionFeedAssembler {
/**
* What the token grants, beyond reading the subscription at all: the UsagePoint service kinds its
- * commodity Function Blocks cover, the summaries, and the HistoryLength ceiling in months.
+ * commodity Function Blocks cover, the summaries, and the HistoryLength ceiling in seconds.
*
* @param serviceKinds null for every UsagePoint (the admin)
*/
public record Grants(Set serviceKinds, boolean usageSummaries,
- boolean powerQualitySummaries, Integer historyLengthMonths) {
+ boolean powerQualitySummaries, Long historyLengthSeconds) {
public static Grants all() {
return new Grants(null, true, true, null);
@@ -275,15 +274,14 @@ private static LinkDto related(String href, String type) {
/**
* Which time-bounded resources a request gets, in epoch seconds. {@code from}/{@code to} bound the overlap
- * (null = open); {@code ceiling} is now minus {@code HistoryLength} months (null = no limit).
+ * (null = open); {@code ceiling} is now minus {@code HistoryLength} seconds (null = no limit).
*/
private record Selection(Long from, Long to, Long ceiling, Long updatedMin, Long updatedMax,
boolean defaultWindow) {
static Selection of(Range range, Grants grants, Instant now) {
long nowSeconds = now.getEpochSecond();
- Long ceiling = grants.historyLengthMonths() == null ? null
- : now.atOffset(ZoneOffset.UTC).minusMonths(grants.historyLengthMonths()).toEpochSecond();
+ Long ceiling = grants.historyLengthSeconds() == null ? null : nowSeconds - grants.historyLengthSeconds();
boolean defaultWindow = range.publishedMin() == null && range.publishedMax() == null;
Long from = defaultWindow ? Long.valueOf(nowSeconds - DEFAULT_WINDOW_SECONDS) : seconds(range.publishedMin());
return new Selection(from, defaultWindow ? null : seconds(range.publishedMax()), ceiling,
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
index a524b72b..97a706b0 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolver.java
@@ -169,20 +169,22 @@ public List espiScopes(Authentication authentication) {
}
/**
- * The {@code HistoryLength} of the token's usage-data scopes, in months: the shortest among its FB scopes
+ * The {@code HistoryLength} of the token's usage-data scopes, in seconds (REQ.21.6.1.2.1: "The amount of
+ * historical information available from the Data Custodian in seconds"): the shortest among its FB scopes
* that grant any usage-data Function Block (interval metering, a commodity, a usage summary or power
* quality), or empty if none states one. Only a scope with no usage-data FB, such as a customer-data scope
* ({@code FB=51_53_54;HistoryLength=...}), is left out: it does not limit usage data.
*
* @throws IllegalArgumentException if an FB scope does not parse (see {@link #espiScopes})
*/
- public Optional historyLengthMonths(Authentication authentication) {
+ public Optional historyLengthSeconds(Authentication authentication) {
return espiScopes(authentication).stream()
.filter(scope -> scope.functionBlocks().stream()
.anyMatch(fb -> UsageFunctionBlockAuthorities.USAGE_DATA.contains("FB_" + fb)))
.map(EspiScope::historyLength)
.filter(Objects::nonNull)
- .min(Integer::compare);
+ .map(Integer::longValue)
+ .min(Long::compare);
}
/** Whether the caller holds the DataCustodian admin authority. */
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index 958a30f4..f84a1f9a 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -242,22 +242,22 @@ void summaries_need_their_function_blocks() throws Exception {
}
@Test
- @DisplayName("HistoryLength (months) is a ceiling: nothing that ended before now minus it, whatever the range asks for")
+ @DisplayName("HistoryLength (seconds) is a ceiling: nothing that ended before now minus it, whatever the range asks for")
void history_length_is_a_ceiling() throws Exception {
- String oneMonth = fetch(SUBSCRIPTION_A,
- customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=1", "FB_16", "FB_17"),
+ String thirtyDays = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=" + (30 * DAY), "FB_16", "FB_17"),
"published-min", ago(100 * DAY));
- String threeMonths = fetch(SUBSCRIPTION_A,
- customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=3", "FB_16", "FB_17"),
+ String oneYear = fetch(SUBSCRIPTION_A,
+ customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17;HistoryLength=31536000", "FB_16", "FB_17"),
"published-min", ago(100 * DAY));
// The old block ended 39 days ago, the old summaries 60 days ago.
- assertThat(oneMonth)
+ assertThat(thirtyDays)
.contains(RECENT_BLOCK.toString(), USAGE_SUMMARY_A.toString(), QUALITY_SUMMARY_A.toString())
.doesNotContain(OLD_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
- assertThat(threeMonths)
+ assertThat(oneYear)
.contains(OLD_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(), OLD_QUALITY_SUMMARY.toString());
- assertValid(oneMonth);
+ assertValid(thirtyDays);
}
@Test
@@ -269,13 +269,13 @@ void latest_summary_respects_the_ceiling() throws Exception {
subscription(LATEST_SUBSCRIPTION, List.of(usagePointRepository.save(usagePoint))));
// Its only power quality summary ended 60 days ago.
- String oneMonth = fetch(LATEST_SUBSCRIPTION,
- customer(LATEST_SUBSCRIPTION, "FB=1_3_4_5_17;HistoryLength=1", "FB_17"));
- String threeMonths = fetch(LATEST_SUBSCRIPTION,
- customer(LATEST_SUBSCRIPTION, "FB=1_3_4_5_17;HistoryLength=3", "FB_17"));
+ String thirtyDays = fetch(LATEST_SUBSCRIPTION,
+ customer(LATEST_SUBSCRIPTION, "FB=1_3_4_5_17;HistoryLength=" + (30 * DAY), "FB_17"));
+ String oneYear = fetch(LATEST_SUBSCRIPTION,
+ customer(LATEST_SUBSCRIPTION, "FB=1_3_4_5_17;HistoryLength=31536000", "FB_17"));
- assertThat(oneMonth).contains(LATEST_POINT.toString()).doesNotContain(LATEST_QUALITY.toString());
- assertThat(threeMonths).contains(LATEST_QUALITY.toString());
+ assertThat(thirtyDays).contains(LATEST_POINT.toString()).doesNotContain(LATEST_QUALITY.toString());
+ assertThat(oneYear).contains(LATEST_QUALITY.toString());
}
@Test
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
index 4419b6b9..e9e4ddf0 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/scope/ScopeResolverTest.java
@@ -161,27 +161,27 @@ void canReadSubscription() {
}
@Test
- @DisplayName("espiScopes: every FB scope but FB=34_35 (any case); HistoryLength (months) is the shortest usage scope's; a bad FB scope throws")
+ @DisplayName("espiScopes: every FB scope but FB=34_35 (any case); HistoryLength (seconds) is the shortest usage scope's; a bad FB scope throws")
void espiScopes() {
- Authentication scopes = auth(Map.of("scope", List.of("openid", "FB=4_5_16;HistoryLength=13",
- "FB=4_5;HistoryLength=7", "FB=51_53_54;HistoryLength=1", "fb=34_35")));
+ Authentication scopes = auth(Map.of("scope", List.of("openid", "FB=4_5_16;HistoryLength=63072000",
+ "FB=4_5;HistoryLength=31536000", "FB=51_53_54;HistoryLength=86400", "fb=34_35")));
assertThat(resolver.espiScopes(scopes))
.extracting(EspiScope::historyLength)
- .containsExactly(13, 7, 1);
- // The customer-data scope's HistoryLength=1 does not limit usage data...
- assertThat(resolver.historyLengthMonths(scopes)).contains(7);
+ .containsExactly(63_072_000, 31_536_000, 86_400);
+ // The customer-data scope's HistoryLength does not limit usage data...
+ assertThat(resolver.historyLengthSeconds(scopes)).contains(31_536_000L);
// ...but a summary-only scope without FB_4 does.
- assertThat(resolver.historyLengthMonths(auth(Map.of("scope",
- List.of("FB=4_5;HistoryLength=13", "FB=16_17;HistoryLength=1"))))).contains(1);
- assertThat(resolver.historyLengthMonths(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
+ assertThat(resolver.historyLengthSeconds(auth(Map.of("scope",
+ List.of("FB=4_5;HistoryLength=63072000", "FB=16_17;HistoryLength=86400"))))).contains(86_400L);
+ assertThat(resolver.historyLengthSeconds(auth(Map.of("scope", "FB=4_5 openid")))).isEmpty();
assertThat(List.of(
resolver.espiScopes(auth(Map.of("scope", List.of("FB=34_35")))),
resolver.espiScopes(auth(Map.of("scope", List.of("fb=34_35")))),
resolver.espiScopes(auth(Map.of("active", true))),
resolver.espiScopes(null)))
.allSatisfy(result -> assertThat(result).isEmpty());
- assertThatThrownBy(() -> resolver.historyLengthMonths(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x")))))
+ assertThatThrownBy(() -> resolver.historyLengthSeconds(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x")))))
.isInstanceOf(IllegalArgumentException.class);
}
}
From 79f0da17b7a7744feaf043e086a88101fced9eb4 Mon Sep 17 00:00:00 2001
From: "Donald F. Coffin"
Date: Wed, 18 Nov 2026 23:49:51 -0500
Subject: [PATCH 9/9] fix(datacustodian): third #282 review fixes (#279)
- The DC sample ApplicationInformation scopes use HistoryLength=34128000
(seconds) instead of 13.
- The 24-hour default applies only when the request has none of
published-min/max and updated-min/max, so an updated-min poll reaches
corrected data of any age (under the HistoryLength ceiling).
- The feed's self link, and so its UUID v5 id, keeps the query string.
- The Batch/Subscription security rule matches /Batch/Subscription/**.
- CustomerAgreementMapper no longer lists the unused DateTimeIntervalMapper.
Co-Authored-By: Claude Opus 5.5
---
.../customer/CustomerAgreementMapper.java | 4 +---
.../config/SecurityConfiguration.java | 2 +-
.../sample/LocalSampleDataSeedRunner.java | 5 +++--
.../web/api/BatchSubscriptionController.java | 3 ++-
.../web/api/SubscriptionFeedAssembler.java | 12 +++++++++---
.../api/BatchSubscriptionIntegrationTest.java | 17 +++++++++++++++++
6 files changed, 33 insertions(+), 10 deletions(-)
diff --git a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java
index 8304fc52..a3d422d3 100644
--- a/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java
+++ b/openespi-common/src/main/java/org/greenbuttonalliance/espi/common/mapper/customer/CustomerAgreementMapper.java
@@ -23,7 +23,6 @@
import org.greenbuttonalliance.espi.common.dto.customer.CustomerAgreementDto;
import org.greenbuttonalliance.espi.common.mapper.BaseMapperUtils;
import org.greenbuttonalliance.espi.common.mapper.DateTimeMapper;
-import org.greenbuttonalliance.espi.common.mapper.usage.DateTimeIntervalMapper;
import org.mapstruct.Mapper;
import org.mapstruct.Mapping;
@@ -40,8 +39,7 @@
DateTimeMapper.class,
BaseMapperUtils.class,
ElectronicAddressMapper.class,
- StatusMapper.class,
- DateTimeIntervalMapper.class
+ StatusMapper.class
})
public interface CustomerAgreementMapper {
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
index 367c760b..b7fb469e 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/SecurityConfiguration.java
@@ -194,7 +194,7 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http,
// --- Batch/Subscription (#279): FB_4 + an electricity, gas or water FB (FB_5-FB_11), or admin.
// The feed holds only the UsagePoints whose service category a granted FB covers. ---
- .requestMatchers(HttpMethod.GET, "/espi/1_1/resource/Batch/Subscription/*")
+ .requestMatchers(HttpMethod.GET, "/espi/1_1/resource/Batch/Subscription/**")
.access(AuthorizationManagers.anyOf(admin, AuthorizationManagers.allOf(fb4,
AuthorityAuthorizationManager.hasAnyAuthority(
UsageFunctionBlockAuthorities.SERVICE_COMMODITY.toArray(String[]::new)))))
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java
index e6b58a0d..92b38e4c 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/sample/LocalSampleDataSeedRunner.java
@@ -305,9 +305,10 @@ private ApplicationInformationEntity sampleThirdPartyApplication() {
app.setContacts("thirdparty@example.com");
app.setTokenEndpointAuthMethod("client_secret_basic");
app.setClientIdIssuedAt(START);
+ // HistoryLength is in seconds (REQ.21.6.1.2.1): 34128000 = 395 days, as in REQ.21.4.2.1.2.1's example.
app.setScope(Set.of(
- "FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=13",
- "FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=13"));
+ "FB=4_5_15;IntervalDuration=3600;BlockDuration=monthly;HistoryLength=34128000",
+ "FB=4_5_15;IntervalDuration=900;BlockDuration=monthly;HistoryLength=34128000"));
app.setGrantTypes(Set.of(GrantType.AUTHORIZATION_CODE, GrantType.REFRESH_TOKEN, GrantType.CLIENT_CREDENTIALS));
app.setResponseTypes(ResponseType.CODE);
return app;
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
index e7ff0639..a3ce3f9c 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java
@@ -119,7 +119,8 @@ public ResponseEntity getSubscription(
throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "A -min query parameter is after its -max");
}
Range range = new Range(instant(publishedMin), instant(publishedMax), instant(updatedMin), instant(updatedMax));
- String feedHref = ServletUriComponentsBuilder.fromCurrentRequestUri().toUriString();
+ // The self link (and so the feed's UUID v5 id) keeps the query: a different range is a different feed.
+ String feedHref = ServletUriComponentsBuilder.fromCurrentRequest().toUriString();
String resourceBase = feedHref.substring(0, feedHref.indexOf(BATCH_SUBSCRIPTION));
AtomFeedDto feed = assembler.build(subscriptionId, resourceBase, feedHref, grants(authentication), range)
.orElseThrow(() -> new ResponseStatusException(HttpStatus.NOT_FOUND));
diff --git a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
index 63669778..278adf8d 100644
--- a/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
+++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java
@@ -83,10 +83,13 @@
* resources, by their interval, billing period or summary interval, whose end is start + duration):
*
* - {@code published-min}/{@code published-max} select those whose interval overlaps the range;
- * - without either, the default is the last 24 hours, by overlap, plus, for each UsagePoint, its most
+ *
- with none of the four range parameters, the default is the last 24 hours, by overlap, plus, for each
+ * UsagePoint, its most
* recent UsageSummary and its most recent ElectricPowerQualitySummary (summary intervals rarely line up
* with a 24-hour window);
- * - {@code updated-min}/{@code updated-max} select by {@code atom:updated};
+ * - {@code updated-min}/{@code updated-max} select by {@code atom:updated}; they apply to these
+ * time-bounded resources only, since the UsagePoints, MeterReadings, ReadingTypes and LocalTimeParameters
+ * are the parents the selected entries need;
* - {@code HistoryLength} (REQ.21.6.1.2.1: "The amount of historical information available from the Data
* Custodian in seconds") is a ceiling, not a selection: nothing that ended before now minus that many
* seconds is returned, whatever the range asks for.
@@ -282,7 +285,10 @@ private record Selection(Long from, Long to, Long ceiling, Long updatedMin, Long
static Selection of(Range range, Grants grants, Instant now) {
long nowSeconds = now.getEpochSecond();
Long ceiling = grants.historyLengthSeconds() == null ? null : nowSeconds - grants.historyLengthSeconds();
- boolean defaultWindow = range.publishedMin() == null && range.publishedMax() == null;
+ // The 24-hour default only when the request gives no range at all: an updated-min/max poll for
+ // corrections must reach data of any age (still under the HistoryLength ceiling).
+ boolean defaultWindow = range.publishedMin() == null && range.publishedMax() == null
+ && range.updatedMin() == null && range.updatedMax() == null;
Long from = defaultWindow ? Long.valueOf(nowSeconds - DEFAULT_WINDOW_SECONDS) : seconds(range.publishedMin());
return new Selection(from, defaultWindow ? null : seconds(range.publishedMax()), ceiling,
seconds(range.updatedMin()), seconds(range.updatedMax()), defaultWindow);
diff --git a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
index f84a1f9a..6f76f545 100644
--- a/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
+++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java
@@ -220,6 +220,23 @@ void updated_range_selects_by_atom_updated() throws Exception {
"LocalTimeParameters");
}
+ @Test
+ @DisplayName("updated-min alone drops the 24-hour default, and the query is part of the feed's self link")
+ void updated_min_alone_reaches_older_data() throws Exception {
+ // In the URL, as a client sends it (MockMvc's param() would not set the query string).
+ String xml = mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_A
+ + "?updated-min=2000-01-01T00:00:00Z")
+ .with(customer(SUBSCRIPTION_A, "FB=1_3_4_5_16_17", "FB_16", "FB_17")))
+ .andExpect(status().isOk())
+ .andReturn().getResponse().getContentAsString();
+
+ assertThat(xml)
+ .contains(OLD_BLOCK.toString(), RECENT_BLOCK.toString(), OLD_USAGE_SUMMARY.toString(),
+ OLD_QUALITY_SUMMARY.toString())
+ .contains("href=\"" + BASE + "/Batch/Subscription/" + SUBSCRIPTION_A + "?updated-min=");
+ assertValid(xml);
+ }
+
@Test
@DisplayName("a query parameter that is not an xs:dateTime is a 400")
void malformed_query_parameter_is_bad_request() throws Exception {