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/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-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/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-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 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 @@ -193,6 +192,13 @@ public SecurityFilterChain securityFilterChain(HttpSecurity http, "/espi/1_1/resource/RetailCustomer/*/UsagePoint/*/ElectricPowerQualitySummary/**") .access(powerQuality) + // --- 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, AuthorizationManagers.allOf(fb4, + AuthorityAuthorizationManager.hasAnyAuthority( + UsageFunctionBlockAuthorities.SERVICE_COMMODITY.toArray(String[]::new))))) + // --- Usage data (GET, read-only) : FB_4 + commodity, or admin --- .requestMatchers(HttpMethod.GET, "/espi/1_1/resource/UsagePoint/**", @@ -290,10 +296,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..8a79e535 --- /dev/null +++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/config/UsageFunctionBlockAuthorities.java @@ -0,0 +1,110 @@ +/* + * + * 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.domain.usage.enums.ServiceKind; +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; + +/** + * 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(); + + /** + * 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(); + + /** + * 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() { + } + + /** + * 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 serviceKinds(Authentication authentication) { + Set kinds = EnumSet.noneOf(ServiceKind.class); + if (authentication == null) { + return kinds; + } + for (GrantedAuthority granted : authentication.getAuthorities()) { + String name = granted.getAuthority(); + if (name != null && SERVICE_COMMODITY.contains(name)) { + FunctionBlock.serviceKindOf(Integer.parseInt(name.substring(3))).ifPresent(kinds::add); + } + } + return kinds; + } + + /** 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/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 new file mode 100644 index 00000000..a3ce3f9c --- /dev/null +++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionController.java @@ -0,0 +1,163 @@ +/* + * + * 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.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; +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.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; + +/** + * {@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 (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") +@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 = "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)") + } + ) + 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); + } + 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)); + // 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)); + + 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 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(); + } + Long historyLength; + try { + historyLength = scopeResolver.historyLengthSeconds(authentication).orElse(null); + } catch (IllegalArgumentException ex) { + throw new ResponseStatusException(HttpStatus.FORBIDDEN, "Unreadable ESPI scope"); + } + return new Grants( + 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 new file mode 100644 index 00000000..278adf8d --- /dev/null +++ b/openespi-datacustodian/src/main/java/org/greenbuttonalliance/espi/datacustodian/web/api/SubscriptionFeedAssembler.java @@ -0,0 +1,353 @@ +/* + * + * 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.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; +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.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}). + * + *

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; 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):

+ *
    + *
  1. the UsagePoint;
  2. + *
  3. each MeterReading, its ReadingType (once in the feed, even if shared) and its IntervalBlocks;
  4. + *
  5. the UsageSummaries and ElectricPowerQualitySummaries, when the token's Function Blocks grant them;
  6. + *
  7. its LocalTimeParameters (once in the feed, even if shared).
  8. + *
+ * + *

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.

+ * + *

Which IntervalBlocks, UsageSummaries and ElectricPowerQualitySummaries are returned (the "time-bounded" + * resources, by their interval, billing period or summary interval, whose end is start + duration):

+ * + *

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: the UsagePoint service kinds its + * 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, Long historyLengthSeconds) { + + public static Grants all() { + return new Grants(null, true, true, null); + } + + boolean covers(UsagePointEntity usagePoint) { + return serviceKinds == null + || ServiceKind.of(usagePoint.getServiceCategory()).map(serviceKinds::contains).orElse(false); + } + } + + /** 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; + 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 final 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; + } + + /** + * 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, + Range range) { + return subscriptionRepository.findById(subscriptionId) + .map(subscription -> usageExportService.buildFeedOf(feedHref, "Subscription", + "Green Button Subscription Feed", + entries(subscription, resourceBase, grants, Selection.of(range, grants, clock.instant())))); + } + + private List entries(SubscriptionEntity subscription, String resourceBase, Grants grants, + Selection selection) { + String subscriptionHref = resourceBase + "/Subscription/" + subscription.getId(); + Set readingTypesInFeed = new HashSet<>(); + Set localTimesInFeed = new HashSet<>(); + List entries = new ArrayList<>(); + + List usagePoints = sorted(subscription.getUsagePoints(), BY_ID).stream() + .filter(grants::covers) + .toList(); + for (UsagePointEntity usagePoint : usagePoints) { + String usagePointFeed = subscriptionHref + "/UsagePoint"; + String usagePointHref = usagePointFeed + "/" + usagePoint.getId(); + List summaries = !grants.usageSummaries() ? List.of() + : selection.summaries(usagePoint.getUsageSummaries(), UsageSummaryEntity::getBillingPeriod); + List qualitySummaries = !grants.powerQualitySummaries() ? List.of() + : selection.summaries(usagePoint.getElectricPowerQualitySummaries(), + ElectricPowerQualitySummaryEntity::getSummaryInterval); + 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 : sorted(usagePoint.getMeterReadings(), BY_ID)) { + addMeterReading(entries, meterReading, usagePointHref, resourceBase, selection, 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 && localTimesInFeed.add(localTime.getId())) { + 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, Selection selection, Set readingTypesInFeed) { + String meterReadingFeed = usagePointHref + "/MeterReading"; + String meterReadingHref = meterReadingFeed + "/" + meterReading.getId(); + ReadingTypeEntity readingType = meterReading.getReadingType(); + List blocks = selection.blocks(meterReading.getIntervalBlocks()); + + 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())); + } + } + + private static List sorted(List items, Comparator 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} 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.historyLengthSeconds() == null ? null : nowSeconds - grants.historyLengthSeconds(); + // 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); + } + + /** 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 6862fca5..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 @@ -19,13 +19,21 @@ 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.greenbuttonalliance.espi.datacustodian.config.UsageFunctionBlockAuthorities; 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.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; @@ -110,15 +118,93 @@ public ResourceScope resolve(Authentication authentication) { return ResourceScope.of(usagePointIds, retailCustomerIds); } - private boolean hasAdminAuthority(Authentication authentication) { + /** + * 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(); + } + + /** + * 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 List espiScopes(Authentication authentication) { + if (authentication == null || !(authentication.getPrincipal() instanceof OAuth2AuthenticatedPrincipal principal)) { + 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.equalsIgnoreCase(text)) { + parsed.add(EspiScope.parse(text)); + } + } + return parsed; + } + + /** + * 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 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) + .map(Integer::longValue) + .min(Long::compare); + } + + /** 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 (ADMIN_AUTHORITY.equals(authority.getAuthority())) { + if (name.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) { Object value = principal.getAttribute(name); if (value == null) { 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 new file mode 100644 index 00000000..6f76f545 --- /dev/null +++ b/openespi-datacustodian/src/test/java/org/greenbuttonalliance/espi/datacustodian/web/api/BatchSubscriptionIntegrationTest.java @@ -0,0 +1,597 @@ +/* + * + * 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.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; +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 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"); + 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"); + 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; + + @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() { + 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("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; + 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", 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("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 { + 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 { + String xml = fetch(SUBSCRIPTION_A, customer(SUBSCRIPTION_A, "FB=1_3_4_5")); + + assertThat(xml) + .doesNotContain(" 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")); + + 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()); + assertValid(gasAndWater); + // FB_4 alone, FB_4 with only temperature (FB_29, #283), and a commodity FB without FB_4 are refused. + for (RequestPostProcessor refused : List.of( + token(MIXED_SUBSCRIPTION, "FB=1_3_4", "FB_4"), + token(MIXED_SUBSCRIPTION, "FB=1_3_4_29", "FB_4", "FB_29"), + token(MIXED_SUBSCRIPTION, "FB=1_3_5", "FB_5"))) { + mockMvc.perform(get(BASE + "/Batch/Subscription/" + MIXED_SUBSCRIPTION).with(refused)) + .andExpect(status().isForbidden()); + } + assertThat(fetch(MIXED_SUBSCRIPTION, admin())) + .contains(ELECTRIC_POINT.toString(), GAS_POINT.toString(), WATER_POINT.toString()); + } + + @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 = usagePoint(id, 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); + } + + @Test + @DisplayName("a token for subscription A gets 403 for B and for an unknown subscription, alike") + void other_subscriptions_are_forbidden() throws Exception { + RequestPostProcessor tokenA = customer(SUBSCRIPTION_A, "FB=1_3_4_5"); + + mockMvc.perform(get(BASE + "/Batch/Subscription/" + SUBSCRIPTION_B).with(tokenA)) + .andExpect(status().isForbidden()); + mockMvc.perform(get(BASE + "/Batch/Subscription/" + UUID.randomUUID()).with(tokenA)) + .andExpect(status().isForbidden()); + } + + @Test + @DisplayName("a Third Party's client access token is refused, even with energy FBs and a matching resourceURI") + void client_access_token_is_refused() throws Exception { + RequestPostProcessor clientToken = opaqueToken() + .attributes(attributes -> 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 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); + 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 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) { + UsagePointEntity usagePoint = new UsagePointEntity(); + usagePoint.setId(USAGE_POINT_A); + usagePoint.setDescription("Sample residential electric service"); + usagePoint.setStatus((short) 1); + usagePoint.setServiceCategory(ServiceCategory.ELECTRICITY); + + usagePoint.setLocalTimeParameters(localTime(LOCAL_TIME_A)); + + 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 - 40 * 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 - 35 * DAY)); + usagePoint.getElectricPowerQualitySummaries().add(qualitySummary(OLD_QUALITY_SUMMARY, usagePoint, now - 90 * DAY)); + 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); + 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(); + summary.setId(id); + summary.setUsagePoint(usagePoint); + summary.setBillingPeriod(new DateTimeInterval(30 * DAY, start)); + summary.setStatusTimeStamp(now); + 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(id); + quality.setUsagePoint(usagePoint); + quality.setSummaryInterval(new DateTimeInterval(30 * DAY, start)); + 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); + return quality; + } + + 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..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 @@ -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; @@ -134,4 +136,52 @@ 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("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=63072000", + "FB=4_5;HistoryLength=31536000", "FB=51_53_54;HistoryLength=86400", "fb=34_35"))); + + assertThat(resolver.espiScopes(scopes)) + .extracting(EspiScope::historyLength) + .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.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.historyLengthSeconds(auth(Map.of("scope", List.of("FB=4_5", "FB=4_x"))))) + .isInstanceOf(IllegalArgumentException.class); + } }