feat: separate feed and subscription data

Author: Sporiff

compose.yaml

@@ -1,12 +1,12 @@
 services:
   postgres:
-    image: 'postgres:latest'
+    image: 'postgres:18'
     env_file:
       - .env
     ports:
       - '5432:5432'
     volumes:
-      - postgres_data:/var/lib/postgresql/data
+      - postgres_data:/var/lib/postgresql
 
   redis:
     image: 'redis:latest'

src/main/java/org/openpodcastapi/opa/feed/FeedDTO.java

@@ -0,0 +1,18 @@
+package org.openpodcastapi.opa.feed;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import jakarta.validation.constraints.NotNull;
+import org.hibernate.validator.constraints.UUID;
+
+/// DTO records for feed entities
+public class FeedDTO {
+    /// A DTO representing a new subscription
+    ///
+    /// @param feedUrl the URL of the feed
+    /// @param uuid    the UUID of the feed calculated by the client
+    public record NewFeedRequestDTO(
+            @JsonProperty(required = true) @NotNull @UUID String uuid,
+            @JsonProperty(required = true) @NotNull String feedUrl
+    ) {
+    }
+}

src/main/java/org/openpodcastapi/opa/feed/FeedEntity.java

@@ -0,0 +1,108 @@
+package org.openpodcastapi.opa.feed;
+
+import jakarta.persistence.*;
+import org.openpodcastapi.opa.subscription.SubscriptionEntity;
+
+import java.time.Instant;
+import java.util.Set;
+import java.util.UUID;
+
+/// An entity representing podcast feed metadata
+@Entity
+@Table(name = "feeds")
+public class FeedEntity {
+    /// The feed's database ID
+    @Id
+    @GeneratedValue(strategy = GenerationType.IDENTITY)
+    private Long id;
+
+    /// The UUIDv5 identifier for the feed.
+    @Column(unique = true, nullable = false, updatable = false, columnDefinition = "uuid")
+    private UUID uuid;
+
+    /// The URL of the subscription feed
+    @Column(nullable = false)
+    private String feedUrl;
+
+    /// Linked subscriptions
+    @OneToMany(mappedBy = "feed", cascade =  CascadeType.REMOVE)
+    private Set<SubscriptionEntity> subscriptions;
+
+    /// Creation timestamp
+    private Instant createdAt;
+
+    /// Last update timestamp
+    private Instant updatedAt;
+
+    /// No-args constructor
+    public FeedEntity() {
+    }
+
+    /// Required-args constructor
+    /// @param uuid the calculated UUIDv5 identifier for the feed
+    /// @param feedUrl the URL location of the feed's XML file
+    public FeedEntity(UUID uuid, String feedUrl) {
+        this.uuid = uuid;
+        this.feedUrl = feedUrl;
+    }
+
+    /// Updates timestamps before saving
+    @PrePersist
+    public void prePersist() {
+        final Instant timestamp = Instant.now();
+        this.setCreatedAt(timestamp);
+        this.setUpdatedAt(timestamp);
+    }
+
+    /// Updates the last updated timestamp when the entity is updated
+    @PreUpdate
+    public void preUpdate() {
+        final Instant timestamp = Instant.now();
+        this.setUpdatedAt(timestamp);
+    }
+
+    /// @return the feed entity ID
+    public Long getId() {
+        return id;
+    }
+
+    /// @return the feed's UUIDv5 identifier
+    public UUID getUuid() {
+        return uuid;
+    }
+
+    /// @param uuid the calculated UUIDv5 identifier for the feed
+    public void setUuid(UUID uuid) {
+        this.uuid = uuid;
+    }
+
+    /// @return the feed's URL
+    public String getFeedUrl() {
+        return feedUrl;
+    }
+
+    /// @param feedUrl the feed's URL
+    public void setFeedUrl(String feedUrl) {
+        this.feedUrl = feedUrl;
+    }
+
+    /// @return the `createdAt` timestamp for the feed entity
+    public Instant getCreatedAt() {
+        return createdAt;
+    }
+
+    /// @param createdAt the creation timestamp
+    public void setCreatedAt(Instant createdAt) {
+        this.createdAt = createdAt;
+    }
+
+    /// @return the `updatedAt` timestamp for the feed entity
+    public Instant getUpdatedAt() {
+        return updatedAt;
+    }
+
+    /// @param updatedAt the new `updatedAt` timestamp
+    public void setUpdatedAt(Instant updatedAt) {
+        this.updatedAt = updatedAt;
+    }
+}

src/main/java/org/openpodcastapi/opa/feed/FeedMapper.java

@@ -0,0 +1,14 @@
+package org.openpodcastapi.opa.feed;
+
+import org.mapstruct.Mapper;
+import org.mapstruct.ReportingPolicy;
+
+/// Helper class to map feed entities and DTOs
+@Mapper(componentModel = "spring", unmappedTargetPolicy = ReportingPolicy.IGNORE)
+public interface FeedMapper {
+    /// Maps an incoming feed creation request to an entity
+    ///
+    /// @param dto the DTO to map
+    /// @return a mapped [FeedEntity]
+    FeedEntity toEntity(FeedDTO.NewFeedRequestDTO dto);
+}

src/main/java/org/openpodcastapi/opa/feed/FeedRepository.java

@@ -0,0 +1,18 @@
+package org.openpodcastapi.opa.feed;
+
+import org.jspecify.annotations.NonNull;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.stereotype.Repository;
+
+import java.util.Optional;
+import java.util.UUID;
+
+/// Repository for subscription feed interactions
+@Repository
+public interface FeedRepository extends JpaRepository<@NonNull FeedEntity, @NonNull Long> {
+    /// Finds a single subscription by UUID.
+    ///
+    /// @param uuid the UUIDv5 value to match
+    /// @return an optional [FeedEntity] match
+    Optional<FeedEntity> findByUuid(UUID uuid);
+}

src/main/java/org/openpodcastapi/opa/feed/FeedService.java

@@ -0,0 +1,42 @@
+package org.openpodcastapi.opa.feed;
+
+import org.slf4j.Logger;
+import org.springframework.stereotype.Service;
+
+import java.util.UUID;
+
+import static org.slf4j.LoggerFactory.getLogger;
+
+/// Service for feed operations
+@Service
+public class FeedService {
+    private static final Logger log = getLogger(FeedService.class);
+    private final FeedRepository repository;
+    private final FeedMapper mapper;
+
+    /// All-args constructor
+    ///
+    /// @param repository the [FeedRepository] for database interactions
+    /// @param mapper     the [FeedMapper] for DTO mapping
+    public FeedService(FeedRepository repository, FeedMapper mapper) {
+        this.repository = repository;
+        this.mapper = mapper;
+    }
+
+    /// Fetches an existing repository from the database or creates a new one if none is found
+    ///
+    /// @param dto the DTO containing the subscription data
+    /// @return the fetched or created subscription
+    public FeedEntity fetchOrCreateFeed(FeedDTO.NewFeedRequestDTO dto) {
+        final var feedUuid = UUID.fromString(dto.uuid());
+
+        log.debug("Searching for existing feed with UUID {}", feedUuid);
+
+        return repository
+                .findByUuid(feedUuid)
+                .orElseGet(() -> {
+                    log.info("Creating new subscription with UUID {} and feed URL {}", dto.uuid(), dto.feedUrl());
+                    return repository.save(mapper.toEntity(dto));
+                });
+    }
+}

src/main/java/org/openpodcastapi/opa/subscription/SubscriptionDTO.java

@@ -3,7 +3,6 @@
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import jakarta.annotation.Nullable;
-import jakarta.validation.constraints.NotNull;
 import org.hibernate.validator.constraints.URL;
 import org.hibernate.validator.constraints.UUID;
 import org.jspecify.annotations.NonNull;
@@ -14,16 +13,6 @@
 
 /// Container for all subscription-related data transfer objects
 public class SubscriptionDTO {
-    /// A DTO representing a new subscription
-    ///
-    /// @param feedUrl the URL of the feed
-    /// @param uuid    the UUID of the feed calculated by the client
-    public record SubscriptionCreateDTO(
-            @JsonProperty(required = true) @NotNull @UUID String uuid,
-            @JsonProperty(required = true) @NotNull String feedUrl
-    ) {
-    }
-
     /// A DTO representing a user's subscription to a given feed
     ///
     /// @param uuid           the feed UUID