Add concrete JsPlugin (#4925)

This PR gives a concrete structure to JsPlugin; name, version, main, root, and paths. All existing means of configuration for JS plugins delegates to JsPlugin. Java jars can now provide JS plugins with this change as well.

This is also a _partial_ improvement for #4817 (JS Plugins development is slow), in that JsPlugin paths is a mean to reduce the scope of files that needs to be copied. This is _not_ a full solution (which may involve routing paths in Jetty that lead directly to the resources as configured via the JS plugins).

For NPM packages, this PR takes a practical approach as opposed to a "perfect" approach; we are requiring that all "real" files be included under the top-level directory as specified by package.json/main. For example, if main is "build/index.js", we'll include everything under "build/". If main is "dist/bundle/index.js", we'll include everything under "dist/".

Adds testing, fixes #4893

docker/registry/server-base/gradle.properties

@@ -1,3 +1,3 @@
 io.deephaven.project.ProjectType=DOCKER_REGISTRY
 deephaven.registry.imageName=ghcr.io/deephaven/server-base:edge
-deephaven.registry.imageId=ghcr.io/deephaven/server-base@sha256:bd59f63831db8ff86c3ebab21ffecd1804e58dcfaaf08a67bf0c2b320a2ce179
+deephaven.registry.imageId=ghcr.io/deephaven/server-base@sha256:8f9b993a4ce7c78b50b869be840241a0a9d19d3f4f35601f20cd05475abd5753

docker/server-jetty/src/main/server-jetty/requirements.txt

@@ -1,7 +1,7 @@
 adbc-driver-manager==0.8.0
 adbc-driver-postgresql==0.8.0
 connectorx==0.3.2; platform.machine == 'x86_64'
-deephaven-plugin==0.5.0
+deephaven-plugin==0.6.0
 java-utilities==0.2.0
 jedi==0.18.2
 jpy==0.14.0

docker/server/src/main/server-netty/requirements.txt

@@ -1,7 +1,7 @@
 adbc-driver-manager==0.8.0
 adbc-driver-postgresql==0.8.0
 connectorx==0.3.2; platform.machine == 'x86_64'
-deephaven-plugin==0.5.0
+deephaven-plugin==0.6.0
 java-utilities==0.2.0
 jedi==0.18.2
 jpy==0.14.0

plugin/src/main/java/io/deephaven/plugin/Plugin.java

@@ -10,6 +10,7 @@
  * A plugin is a structured extension point for user-definable behavior.
  *
  * @see ObjectType
+ * @see JsPlugin
  */
 public interface Plugin extends Registration {
 

plugin/src/main/java/io/deephaven/plugin/js/JsPlugin.java

@@ -3,16 +3,145 @@
  */
 package io.deephaven.plugin.js;
 
+import io.deephaven.annotations.BuildableStyle;
 import io.deephaven.plugin.Plugin;
+import io.deephaven.plugin.PluginBase;
+import org.immutables.value.Value.Check;
+import org.immutables.value.Value.Default;
+import org.immutables.value.Value.Immutable;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
 
 /**
- * A js plugin is a {@link Plugin} that allows adding javascript code under the server's URL path "js-plugins/". See
- * <a href="https://github.com/deephaven/deephaven-plugins#js-plugins">deephaven-plugins#js-plugins</a> for more details
- * about the underlying construction for js plugins.
+ * A JS plugin is a {@link Plugin} that allows for custom javascript and related content to be served, see
+ * {@link io.deephaven.plugin.js}.
+ *
+ * <p>
+ * For example, if the following JS plugin was the only JS plugin installed
+ *
+ * <pre>
+ * JsPlugin.builder()
+ * .name("foo")
+ * .version("1.0.0")
+ * .main(Path.of("dist/index.js"))
+ * .path(Path.of("/path-to/my-plugin"))
+ * .build()
+ * </pre>
+ *
+ * the manifest served at "js-plugins/manifest.json" would be equivalent to
+ *
+ * <pre>
+ * {
+ * "plugins": [
+ * {
+ * "name": "foo",
+ * "version": "1.0.0",
+ * "main": "dist/index.js"
+ * }
+ * ]
+ * }
+ * </pre>
  *
- * @see JsPluginPackagePath
- * @see JsPluginManifestPath
+ * and the file "/path-to/my-plugin/dist/index.js" would be served at "js-plugins/foo/dist/index.js". All other files of
+ * the form "/path-to/my-plugin/{somePath}" will be served at "js-plugins/foo/{somePath}".
  */
-public interface JsPlugin extends Plugin {
+@Immutable
+@BuildableStyle
+public abstract class JsPlugin extends PluginBase {
+
+ public static Builder builder() {
+ return ImmutableJsPlugin.builder();
+ }
+
+ /**
+ * The JS plugin name. The JS plugin contents will be served via the URL path "js-plugins/{name}/", as well as
+ * included as the "name" field for the manifest entry in "js-plugins/manifest.json".
+ *
+ * @return the name
+ */
+ public abstract String name();
+
+ /**
+ * The JS plugin version. Will be included as the "version" field for the manifest entry in
+ * "js-plugins/manifest.json".
+ *
+ * @return the version
+ */
+ public abstract String version();
+
+ /**
+ * The main JS file path, specified relative to {@link #path()}. The main JS file must exist
+ * ({@code Files.isRegularFile(root().resolve(main()))}) and must be included in {@link #paths()}. Will be included
+ * as the "main" field for the manifest entry in "js-plugins/manifest.json".
+ *
+ * @return the main JS file path
+ */
+ public abstract Path main();
+
+ /**
+ * The directory path of the resources to serve. The resources will be served via the URL path
+ * "js-plugins/{name}/{relativeToPath}". The path must exist ({@code Files.isDirectory(path())}).
+ *
+ * @return the path
+ */
+ public abstract Path path();
+
+ /**
+ * The subset of resources from {@link #path()} to serve. Production installations should preferably be packaged
+ * with the exact resources necessary (and thus served with {@link Paths#all()}). During development, other subsets
+ * may be useful if {@link #path()} contains content unrelated to the JS content. By default, is
+ * {@link Paths#all()}.
+ *
+ * @return the paths
+ */
+ @Default
+ public Paths paths() {
+ return Paths.all();
+ }
+
+ @Override
+ public final <T, V extends Plugin.Visitor<T>> T walk(V visitor) {
+ return visitor.visit(this);
+ }
+
+ @Check
+ final void checkPath() {
+ if (!Files.isDirectory(path())) {
+ throw new IllegalArgumentException(String.format("path ('%s') must exist and be a directory", path()));
+ }
+ }
+
+ @Check
+ final void checkMain() {
+ final Path mainPath = path().resolve(main());
+ if (!Files.isRegularFile(mainPath)) {
+ throw new IllegalArgumentException(String.format("main ('%s') must exist and be a regular file", mainPath));
+ }
+ }
+
+ @Check
+ final void checkPaths() {
+ if (!(paths() instanceof PathsInternal)) {
+ throw new IllegalArgumentException("Must construct one of the approved Paths");
+ }
+ final Path relativeMain = path().relativize(path().resolve(main()));
+ if (!((PathsInternal) paths()).matches(relativeMain)) {
+ throw new IllegalArgumentException(String.format("main ('%s') is not in paths", relativeMain));
+ }
+ }
+
+ public interface Builder {
+ Builder name(String name);
+
+ Builder version(String version);
+
+ Builder main(Path main);
+
+ Builder path(Path path);
+
+ Builder paths(Paths paths);
 
+ JsPlugin build();
+ }
 }

plugin/src/main/java/io/deephaven/plugin/js/Paths.java

@@ -0,0 +1,53 @@
+/**
+ * Copyright (c) 2016-2023 Deephaven Data Labs and Patent Pending
+ */
+package io.deephaven.plugin.js;
+
+import java.nio.file.Path;
+
+/**
+ * The subset of paths to serve, see {@link JsPlugin#paths()}.
+ */
+public interface Paths {
+
+ /**
+ * Includes all paths.
+ *
+ * @return the paths
+ */
+ static Paths all() {
+ return PathsAll.ALL;
+ }
+
+ /**
+ * Includes only the paths that are prefixed by {@code prefix}.
+ *
+ * @param prefix the prefix
+ * @return the paths
+ */
+ static Paths ofPrefixes(Path prefix) {
+ // Note: we have specific overload for single element to explicitly differentiate from Iterable overload since
+ // Path extends Iterable<Path>.
+ return PathsPrefixes.builder().addPrefixes(prefix).build();
+ }
+
+ /**
+ * Includes only the paths that are prefixed by one of {@code prefixes}.
+ *
+ * @param prefixes the prefixes
+ * @return the paths
+ */
+ static Paths ofPrefixes(Path... prefixes) {
+ return PathsPrefixes.builder().addPrefixes(prefixes).build();
+ }
+
+ /**
+ * Includes only the paths that are prefixed by one of {@code prefixes}.
+ *
+ * @param prefixes the prefixes
+ * @return the paths
+ */
+ static Paths ofPrefixes(Iterable<? extends Path> prefixes) {
+ return PathsPrefixes.builder().addAllPrefixes(prefixes).build();
+ }
+}

plugin/src/main/java/io/deephaven/plugin/js/PathsAll.java

@@ -0,0 +1,15 @@
+/**
+ * Copyright (c) 2016-2023 Deephaven Data Labs and Patent Pending
+ */
+package io.deephaven.plugin.js;
+
+import java.nio.file.Path;
+
+enum PathsAll implements PathsInternal {
+ ALL;
+
+ @Override
+ public boolean matches(Path path) {
+ return true;
+ }
+}

plugin/src/main/java/io/deephaven/plugin/js/PathsInternal.java

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) 2016-2023 Deephaven Data Labs and Patent Pending
+ */
+package io.deephaven.plugin.js;
+
+import java.nio.file.PathMatcher;
+
+interface PathsInternal extends Paths, PathMatcher {
+
+}