Pal 1023 s3 interceptor client

client-akka/src/main/java/uk/gov/gchq/palisade/client/akka/AkkaClient.java

@@ -57,6 +57,10 @@
 public class AkkaClient implements Client {
     private static final ObjectMapper MAPPER = new ObjectMapper();
 
+    /**
+     * Specify URL schemes based on whether SSL/TLS encryption should be used over-the-wire.
+     * Ingress to the cluster may use TLS, while cluster-internal comms may use plaintext.
+     */
     public enum SSLMode {
         NONE("http", "ws"),
         SSL_TLS("https", "wss");

client-java/src/contract-tests/java/uk/gov/gchq/palisade/contract/java/FullTest.java

@@ -17,10 +17,7 @@
 
 import io.micronaut.runtime.server.EmbeddedServer;
 import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
-import io.reactivex.rxjava3.annotations.NonNull;
 import io.reactivex.rxjava3.core.Flowable;
-import io.reactivex.rxjava3.core.FlowableSubscriber;
-import org.assertj.core.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.reactivestreams.FlowAdapters;
 import org.slf4j.Logger;
@@ -85,6 +82,8 @@ void testWithDownloadOutsideStream() throws Exception {
 
     }
 
+    // RxJava .subscribe(..) returns an unused disposable
+    @SuppressWarnings("ResultOfMethodCallIgnored")
     @Test
     void testWithDownloadInsideStream() throws Exception {
 
@@ -99,10 +98,7 @@ void testWithDownloadInsideStream() throws Exception {
             .filter(m -> m.getType().equals(ItemType.RESOURCE))
             .map(session::fetch)
             .timeout(10, TimeUnit.SECONDS)
-            .subscribe(new FlowableSubscriber<>() {
-
-                @Override
-                public void onNext(final Download t) {
+            .subscribe((final Download t) -> {
                     LOGGER.debug("## Got message: {}", t);
                     try (var is = t.getInputStream()) {
                         LOGGER.debug("## reading bytes");
@@ -113,25 +109,6 @@ public void onNext(final Download t) {
                         LOGGER.error("Got error reading input stream into byte array", e);
                         throw new IllegalStateException("Got error reading input stream into byte array", e);
                     }
-                }
-
-                @Override
-                public void onError(final Throwable t) {
-                    LOGGER.error("## Error: {}", t.getMessage());
-                    Assertions.fail("Failed due to:" + t.getMessage());
-                }
-
-                @Override
-                public void onComplete() {
-                    LOGGER.debug("## complete");
-
-                }
-
-                @Override
-                public void onSubscribe(final org.reactivestreams.@NonNull Subscription s) {
-                    s.request(Long.MAX_VALUE);
-                    LOGGER.debug("## Subscribed");
-                }
-            });
+                });
     }
 }

client-s3/README.md

@@ -16,6 +16,10 @@
  */
 -->
 
+# <img src="../logos/logo.svg" width="180">
+
+## A Tool for Complex and Scalable Data Access Policy Enforcement
+
 > :information_source: ***Work In Progress***
 > There are some issues between what Spark expects and what the server returns for a `GetObject`.
 > The server returns a valid AVRO object (which can be successfully read if written to a file).

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/config/EndpointConfiguration.java → client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/config/ApplicationConfiguration.java

@@ -27,22 +27,25 @@
 import uk.gov.gchq.palisade.Generated;
 import uk.gov.gchq.palisade.client.akka.AkkaClient;
 import uk.gov.gchq.palisade.client.akka.AkkaClient.SSLMode;
-import uk.gov.gchq.palisade.client.s3.config.EndpointConfiguration.ClientMap;
+import uk.gov.gchq.palisade.client.s3.config.ApplicationConfiguration.ClientMap;
 import uk.gov.gchq.palisade.client.s3.repository.ContentLengthRepository;
 import uk.gov.gchq.palisade.client.s3.repository.PersistenceLayer;
 import uk.gov.gchq.palisade.client.s3.repository.ResourceRepository;
 import uk.gov.gchq.palisade.client.s3.web.AkkaHttpServer;
+import uk.gov.gchq.palisade.client.s3.web.DynamicS3ServerApi;
 import uk.gov.gchq.palisade.client.s3.web.RouteSupplier;
-import uk.gov.gchq.palisade.client.s3.web.S3ServerApi;
 
 import java.net.InetAddress;
 import java.util.Collection;
 import java.util.Map;
 import java.util.Optional;
 
+/**
+ * Spring bean dependency injection graph
+ */
 @Configuration
 @EnableConfigurationProperties(ClientMap.class)
-public class EndpointConfiguration {
+public class ApplicationConfiguration {
 
     @ConfigurationProperties(prefix = "web")
     static class ClientMap {
@@ -53,6 +56,12 @@ public Map<String, String> getClient() {
             return client;
         }
 
+        /**
+         * Get a single url for a service name.
+         *
+         * @param key the name of a service
+         * @return the URL for that service
+         */
         @Generated
         public String getClient(final String key) {
             return client.get(key);
@@ -94,7 +103,7 @@ AkkaClient akkaClient(final ActorSystem actorSystem, final ClientMap clientMap)
 
     @Bean
     RouteSupplier s3ServerApi(final AkkaClient akkaClient, final Materializer materializer, final PersistenceLayer persistenceLayer) {
-        return new S3ServerApi(akkaClient, materializer, persistenceLayer);
+        return new DynamicS3ServerApi(akkaClient, materializer, persistenceLayer);
     }
 
     @Bean

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/config/JacksonXmlSupport.java

@@ -30,11 +30,25 @@
 import java.util.Arrays;
 import java.util.List;
 
-public class JacksonXmlSupport {
+/**
+ * Configure Jackson for XML serialisation and deserialisation.
+ * S3 is built on XML for message request/response types, whereas Jackson defaults to JSON.
+ */
+public final class JacksonXmlSupport {
     private static final List<MediaType> XML_MEDIA_TYPES = Arrays.asList(MediaTypes.APPLICATION_XML, MediaTypes.TEXT_XML);
     private static final ObjectMapper DEFAULT_XML_MAPPER = new XmlMapper()
             .enable(SerializationFeature.WRAP_ROOT_VALUE);
 
+    private JacksonXmlSupport() {
+        // Hide public constructor for static-method-only class
+    }
+
+    /**
+     * Create a Jackson {@link Marshaller} for serialising to the XML media-type.
+     *
+     * @param <T> the domain type for the marshaller
+     * @return a new marshaller for converting objects to XML
+     */
     public static <T> Marshaller<T, RequestEntity> marshaller() {
         return Marshaller.wrapEntity(
                 JacksonXmlSupport::toXML,
@@ -43,11 +57,25 @@ public static <T> Marshaller<T, RequestEntity> marshaller() {
         );
     }
 
+    /**
+     * Create a Jackson {@link Unmarshaller} for deserialising from the XML media-type.
+     *
+     * @param expectedType the expected type to deserialise the XML into
+     * @param <T> the domain type for the unmarshaller
+     * @return a new unmarshaller for converting XML to objects
+     */
     public static <T> Unmarshaller<HttpEntity, T> unmarshaller(final Class<T> expectedType) {
         return Unmarshaller.forMediaTypes(XML_MEDIA_TYPES, Unmarshaller.entityToString())
                 .thenApply(xml -> fromXML(xml, expectedType));
     }
 
+    /**
+     * Convert a Java object to XML.
+     *
+     * @param object the Java object to convert
+     * @param <T>    the type of the Java object
+     * @return a {@link String} of XML data representing the serialised object
+     */
     private static <T> String toXML(final T object) {
         try {
             return JacksonXmlSupport.DEFAULT_XML_MAPPER.writeValueAsString(object);
@@ -56,6 +84,14 @@ private static <T> String toXML(final T object) {
         }
     }
 
+    /**
+     * Convert an XML String to a Java object.
+     *
+     * @param xml          the Java object to convert
+     * @param expectedType the expected type to deserialise the XML into
+     * @param <T>          the type of the Java object
+     * @return a Java object representing the deserialisation of the XML data
+     */
     private static <T> T fromXML(final String xml, final Class<T> expectedType) {
         try {
             return JacksonXmlSupport.DEFAULT_XML_MAPPER.readerFor(expectedType).readValue(xml);

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/domain/CanonicalUser.java

@@ -24,6 +24,9 @@
 import java.util.StringJoiner;
 
 
+/**
+ * S3 model for the 'CanonicalUser' XML schema.
+ */
 public class CanonicalUser {
 
     @JsonProperty(value = "ID", required = true)

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/domain/ListBucketResult.java

@@ -26,6 +26,11 @@
 import java.util.List;
 import java.util.StringJoiner;
 
+/**
+ * S3 model for the 'ListBucketResult' XML schema.
+ */
+// Schema specifies field 'isTruncated', not 'truncated'
+@SuppressWarnings("java:S2047")
 @JacksonXmlRootElement(localName = "ListBucketResult", namespace = "http://s3.amazonaws.com/doc/2006-03-01/")
 public class ListBucketResult {
 

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/domain/ListEntry.java

@@ -24,6 +24,9 @@
 import java.util.Date;
 import java.util.StringJoiner;
 
+/**
+ * S3 model for the 'ListEntry' XML schema.
+ */
 public class ListEntry {
 
     @JsonProperty(value = "Key", required = true)
@@ -61,12 +64,12 @@ public void setLastModified(final Date lastModified) {
     }
 
     @Generated
-    public String geteTag() {
+    public String getETag() {
         return eTag;
     }
 
     @Generated
-    public void seteTag(final String eTag) {
+    public void setETag(final String eTag) {
         this.eTag = eTag;
     }
 

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/domain/MetadataEntry.java

@@ -23,6 +23,9 @@
 import java.util.StringJoiner;
 
 
+/**
+ * S3 model for the 'MetadataEntry' XML schema.
+ */
 public class MetadataEntry {
 
     @JsonProperty(value = "Name", required = true)

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/domain/PrefixEntry.java

@@ -22,6 +22,9 @@
 
 import java.util.StringJoiner;
 
+/**
+ * S3 model for the 'PrefixEntry' XML schema.
+ */
 public class PrefixEntry {
 
     @JsonProperty(value = "Prefix", required = true)

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/domain/StorageClass.java

@@ -16,17 +16,31 @@
 
 package uk.gov.gchq.palisade.client.s3.domain;
 
+/**
+ * S3 model for the 'StorageClass' XML schema.
+ */
 public enum StorageClass {
 
     STANDARD,
     REDUCED_REDUNDANCY,
     GLACIER,
     UNKNOWN;
 
+    /**
+     * Convert from Enum to String.
+     *
+     * @return a {@link String} representation of the {@link StorageClass}
+     */
     public String value() {
         return name();
     }
 
+    /**
+     * Convert from String to Enum.
+     *
+     * @param v the string to convert to a storageClass enum
+     * @return a {@link StorageClass}
+     */
     public static StorageClass fromValue(final String v) {
         return valueOf(v);
     }

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/repository/AbstractOrphanedChildJsonMixin.java

@@ -26,9 +26,9 @@
  * This includes, for any given persisted resource, its parent id, which will also be persisted.
  * Erase parent when storing JSON, it will be rebuilt using the repository.
  */
-// Must be abstract class, not interface, to be used as mixin
 @JsonTypeInfo(use = JsonTypeInfo.Id.CLASS)
-@SuppressWarnings("java:S1610")
+// Must be abstract class, not interface, to be used as mixin
+@SuppressWarnings({"java:S1610", "java:S1694"})
 public abstract class AbstractOrphanedChildJsonMixin {
     /**
      * Ignore the parent field when serialising to JSON.

client-s3/src/main/java/uk/gov/gchq/palisade/client/s3/repository/ContentLengthRepository.java

@@ -22,23 +22,55 @@
 import java.util.Optional;
 import java.util.concurrent.CompletableFuture;
 
+/**
+ * Repository for storing/caching content-lengths of resources after rules are applied.
+ * Used to inform a client of the S3 server on HTTP Content-Length (e.g. Spark is quite picky about it).
+ */
 public interface ContentLengthRepository extends ReactiveCrudRepository<ContentLengthEntity, String> {
-    int PARALLELISM = 1;
-
+    /**
+     * Is there a length stored for a given resourceId.
+     *
+     * @param id the resourceId to check if there is a length stored
+     * @return true if there is a length stored, false otherwise
+     */
     Mono<Boolean> existsById(String id);
 
+    /**
+     * Get a Content-Length for a resourceId.
+     *
+     * @param id the resourceId to get a length for
+     * @return a {@link ContentLengthEntity} containing the Content-Length
+     */
     Mono<ContentLengthEntity> getByResourceId(String id);
 
+    /**
+     * Is there a length stored for a given resourceId.
+     *
+     * @param id the resourceId to check if there is a length stored
+     * @return true if there is a length stored, false otherwise
+     */
     default CompletableFuture<Boolean> futureExistsById(String id) {
         return existsById(id).toFuture();
     }
 
+    /**
+     * Get a Content-Length for a resourceId.
+     *
+     * @param id the resourceId to get a length for
+     * @return a {@link ContentLengthEntity} containing the Content-Length
+     */
     default CompletableFuture<Optional<ContentLengthEntity>> futureGetByResourceId(String id) {
         return this.getByResourceId(id)
                 .toFuture()
                 .thenApply(Optional::ofNullable);
     }
 
+    /**
+     * Set a Content-Length for a given resourceId.
+     *
+     * @param entity a {@link ContentLengthEntity} that will be stored, indexed by its id
+     * @return the saved {@link ContentLengthEntity}, once it has been saved
+     */
     default CompletableFuture<ContentLengthEntity> futureSave(ContentLengthEntity entity) {
         return this.save(entity)
                 .toFuture();