server: add provider-admin share entities and CRUD

server/opensharing-server-core/src/main/java/io/opensharing/Transactions.java

@@ -0,0 +1,17 @@
+package io.opensharing;
+
+import jakarta.persistence.EntityManager;
+import java.util.function.Function;
+
+/**
+ * Runs store work in one database transaction. Each host supplies its own, backed by its own
+ * persistence setup; OpenSharing's entities must be registered with it.
+ */
+public interface Transactions {
+
+  /**
+   * Runs {@code work} in a new transaction and commits it, or rolls it back when {@code work}
+   * throws. Entities returned from {@code work} are detached once it returns.
+   */
+  <T> T inTransaction(boolean readOnly, Function<EntityManager, T> work);
+}

server/opensharing-server-core/src/main/java/io/opensharing/auth/Ownership.java

@@ -0,0 +1,16 @@
+package io.opensharing.auth;
+
+import io.opensharing.http.ApiException;
+
+/** Ownership checks for objects OpenSharing stores. */
+public final class Ownership {
+
+  private Ownership() {}
+
+  /** Passes only when {@code user} has the id {@code ownerId}; a missing id never matches. */
+  public static void check(UserContext user, String ownerId, String what) {
+    if (user.userId() == null || ownerId == null || !ownerId.equals(user.userId())) {
+      throw ApiException.permissionDenied("user '" + user.userName() + "' does not own " + what);
+    }
+  }
+}

server/opensharing-server-core/src/main/java/io/opensharing/http/ListResponse.java

@@ -0,0 +1,20 @@
+package io.opensharing.http;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.util.List;
+
+/**
+ * Paginated list envelope shared by list endpoints. {@code nextPageToken} is omitted on the last
+ * page:
+ *
+ * <pre>{@code
+ * {"items": [<item>, ...], "nextPageToken": "<page token>"}
+ * }</pre>
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record ListResponse<T>(List<T> items, String nextPageToken) {
+
+  public static <T> ListResponse<T> of(List<T> items) {
+    return new ListResponse<>(items, null);
+  }
+}

server/opensharing-server-core/src/main/java/io/opensharing/runtime/OpenSharing.java

@@ -1,6 +1,11 @@
 package io.opensharing.runtime;
 
+import io.opensharing.Transactions;
 import io.opensharing.catalog.CatalogConnector;
+import io.opensharing.share.ShareEntity;
+import io.opensharing.share.ShareService;
+import io.opensharing.share.ShareStore;
+import java.util.List;
 
 /**
  * OpenSharing assembled from what its host supplies. The standalone server builds one from its
@@ -10,22 +15,34 @@
 public final class OpenSharing {
 
   private final CatalogConnector catalog;
+  private final ShareService shares;
 
-  private OpenSharing(CatalogConnector catalog) {
+  private OpenSharing(CatalogConnector catalog, Transactions tx) {
     this.catalog = catalog;
+    this.shares = new ShareService(catalog, new ShareStore(tx));
   }
 
   public static Builder builder() {
     return new Builder();
   }
 
+  /** The entity classes the host's {@link Transactions} must register. */
+  public static List<Class<?>> entities() {
+    return List.of(ShareEntity.class);
+  }
+
   public CatalogConnector catalog() {
     return catalog;
   }
 
+  public ShareService shares() {
+    return shares;
+  }
+
   public static final class Builder {
 
     private CatalogConnector catalog;
+    private Transactions transactions;
 
     private Builder() {}
 
@@ -35,11 +52,24 @@ public Builder catalog(CatalogConnector catalog) {
       return this;
     }
 
+    /**
+     * How OpenSharing reaches the host's database. OpenSharing keeps its own tables there and runs
+     * every read and write through these transactions, so the host's persistence setup must
+     * register the classes from {@link OpenSharing#entities}. Must be set before {@link #build}.
+     */
+    public Builder transactions(Transactions transactions) {
+      this.transactions = transactions;
+      return this;
+    }
+
     public OpenSharing build() {
       if (catalog == null) {
         throw new IllegalStateException("OpenSharing requires a CatalogConnector from the host");
       }
-      return new OpenSharing(catalog);
+      if (transactions == null) {
+        throw new IllegalStateException("OpenSharing requires Transactions from the host");
+      }
+      return new OpenSharing(catalog, transactions);
     }
   }
 }

server/opensharing-server-core/src/main/java/io/opensharing/share/CreateShareRequest.java

@@ -0,0 +1,7 @@
+package io.opensharing.share;
+
+import java.util.Map;
+
+/** POST body to create a share. The authenticated caller becomes the owner. */
+public record CreateShareRequest(
+    String name, String displayName, String comment, Map<String, String> properties) {}

server/opensharing-server-core/src/main/java/io/opensharing/share/ShareEntity.java

@@ -0,0 +1,96 @@
+package io.opensharing.share;
+
+import io.opensharing.BaseEntity;
+import io.opensharing.ObjectNames;
+import jakarta.persistence.CollectionTable;
+import jakarta.persistence.Column;
+import jakarta.persistence.ElementCollection;
+import jakarta.persistence.Entity;
+import jakarta.persistence.FetchType;
+import jakarta.persistence.JoinColumn;
+import jakarta.persistence.MapKeyColumn;
+import jakarta.persistence.Table;
+import jakarta.persistence.UniqueConstraint;
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+
+/** Persisted share row. {@code name} is always stored lowercase. */
+@Entity
+@Table(
+    name = "os_shares",
+    uniqueConstraints = @UniqueConstraint(name = "uk_shares_name", columnNames = "name"))
+public class ShareEntity extends BaseEntity {
+
+  @Column(nullable = false, length = 255)
+  private String name;
+
+  @Column(name = "display_name", length = 255)
+  private String displayName;
+
+  @Column(length = 8192)
+  private String comment;
+
+  /**
+   * The catalog's user id for whoever created this share. It is not kept in sync with the catalog,
+   * so it goes stale if the catalog removes the user.
+   */
+  @Column(name = "owner_id", nullable = false, length = 255)
+  private String ownerId;
+
+  /**
+   * User-defined key-value properties, one row per key in {@code os_share_properties}. Loaded
+   * eagerly because the share is read after the store's transaction has closed.
+   */
+  @ElementCollection(fetch = FetchType.EAGER)
+  @CollectionTable(
+      name = "os_share_properties",
+      joinColumns = @JoinColumn(name = "share_id"),
+      uniqueConstraints =
+          @UniqueConstraint(
+              name = "uk_share_properties",
+              columnNames = {"share_id", "property_key"}))
+  @MapKeyColumn(name = "property_key", length = 255)
+  @Column(name = "property_value", length = 1000)
+  private Map<String, String> properties = new LinkedHashMap<>();
+
+  public String getName() {
+    return name;
+  }
+
+  public void setName(String name) {
+    this.name = ObjectNames.normalize(name);
+  }
+
+  public String getDisplayName() {
+    return displayName;
+  }
+
+  public void setDisplayName(String displayName) {
+    this.displayName = displayName;
+  }
+
+  public String getComment() {
+    return comment;
+  }
+
+  public void setComment(String comment) {
+    this.comment = comment;
+  }
+
+  public Map<String, String> getProperties() {
+    return Collections.unmodifiableMap(properties);
+  }
+
+  public void setProperties(Map<String, String> properties) {
+    this.properties = properties == null ? new LinkedHashMap<>() : new LinkedHashMap<>(properties);
+  }
+
+  public String getOwnerId() {
+    return ownerId;
+  }
+
+  public void setOwnerId(String ownerId) {
+    this.ownerId = ownerId;
+  }
+}

server/opensharing-server-core/src/main/java/io/opensharing/share/ShareResponse.java

@@ -0,0 +1,35 @@
+package io.opensharing.share;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import java.util.Map;
+
+/**
+ * A share as the protocol reports it. Fields without a value are omitted:
+ *
+ * <pre>{@code
+ * {
+ *   "id": "<share id>",
+ *   "name": "<share name>",
+ *   "displayName": "<display name>",
+ *   "comment": "<comment>",
+ *   "properties": {"<key>": "<value>"}
+ * }
+ * }</pre>
+ */
+@JsonInclude(JsonInclude.Include.NON_NULL)
+public record ShareResponse(
+    String id,
+    String name,
+    String displayName,
+    String comment,
+    Map<String, String> properties) {
+
+  public static ShareResponse from(ShareEntity share) {
+    return new ShareResponse(
+        share.getId(),
+        share.getName(),
+        share.getDisplayName(),
+        share.getComment(),
+        Map.copyOf(share.getProperties()));
+  }
+}

server/opensharing-server-core/src/main/java/io/opensharing/share/ShareService.java

@@ -0,0 +1,79 @@
+package io.opensharing.share;
+
+import io.opensharing.ObjectNames;
+import io.opensharing.auth.AuthContext;
+import io.opensharing.auth.Privilege;
+import io.opensharing.auth.UserContext;
+import io.opensharing.catalog.CatalogConnector;
+import io.opensharing.http.ApiException;
+import io.opensharing.http.ListResponse;
+import java.util.Map;
+
+/**
+ * Provider share CRUD for a caller the host has authenticated. Creating a share needs CREATE_SHARE
+ * from the catalog; any caller may read shares, only the owner may change them.
+ */
+public class ShareService {
+
+  private final CatalogConnector catalog;
+  private final ShareStore shares;
+
+  public ShareService(CatalogConnector catalog, ShareStore shares) {
+    this.catalog = catalog;
+    this.shares = shares;
+  }
+
+  /** Creates a share owned by the caller, who needs CREATE_SHARE from the catalog. */
+  public ShareResponse create(UserContext user, CreateShareRequest request) {
+    // The host has already authenticated the caller. A host that also checks CREATE_SHARE at its
+    // endpoint can make this a no-op.
+    catalog.authorize(AuthContext.of(user), Privilege.CREATE_SHARE);
+    return ShareResponse.from(
+        shares.create(
+            user,
+            ObjectNames.validateShareName(request.name()),
+            request.displayName(),
+            request.comment(),
+            validateProperties(request.properties())));
+  }
+
+  /** Lists every share by name, unpaged. */
+  public ListResponse<ShareResponse> list() {
+    // TODO: page with maxResults and pageToken.
+    // TODO: check USE_SHARE through catalog.authorize.
+    return ListResponse.of(shares.list().stream().map(ShareResponse::from).toList());
+  }
+
+  /** Gets a share by name in any case. */
+  public ShareResponse get(String share) {
+    return ShareResponse.from(shares.getOrThrow(share));
+  }
+
+  /** Updates the fields set in {@code request}. Owner only. */
+  public ShareResponse update(UserContext user, String share, UpdateShareRequest request) {
+    return ShareResponse.from(
+        shares.update(
+            user,
+            share,
+            request.displayName(),
+            request.comment(),
+            validateProperties(request.properties())));
+  }
+
+  /** Deletes the share. Owner only. */
+  public void delete(UserContext user, String share) {
+    shares.delete(share, user);
+  }
+
+  private static Map<String, String> validateProperties(Map<String, String> properties) {
+    if (properties != null) {
+      for (Map.Entry<String, String> property : properties.entrySet()) {
+        if (property.getValue() == null) {
+          throw ApiException.invalidParameter(
+              "property '" + property.getKey() + "' must not be null");
+        }
+      }
+    }
+    return properties;
+  }
+}