Refine HTTP Server (#13156)

* Add "demo" library for http - and adapt path of Chocolate.bib

* Fix tests

* Add little hint on debugging

* Update docs/code-howtos/http-server.md

Co-authored-by: Subhramit Basu <[email protected]>

* Update docs/code-howtos/http-server.md

Co-authored-by: Philip <[email protected]>

* Update jabsrv/src/test/rest-api.http

Co-authored-by: Philip <[email protected]>

---------

Co-authored-by: Subhramit Basu <[email protected]>
Co-authored-by: Philip <[email protected]>

Author: 3 people

.jbang/JabSrvLauncher.java

@@ -0,0 +1,61 @@
+///usr/bin/env jbang "$0" "$@" ; exit $?
+
+//DESCRIPTION jabsrv - serve BibTeX files using JabRef
+
+//JAVA 24
+//RUNTIME_OPTIONS --enable-native-access=ALL-UNNAMED
+
+//SOURCES ../jabsrv-cli/src/main/java/org/jabref/http/server/cli/ServerCli.java
+//FILES tinylog.properties=../jabsrv-cli/src/main/resources/tinylog.properties
+
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/dto/BibEntryDTO.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/dto/GlobalExceptionMapper.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/dto/GsonFactory.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/JabrefMediaType.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/JabRefResourceLocator.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/CORSFilter.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/LibrariesResource.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/LibraryResource.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/PreferencesFactory.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/RootResource.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/Server.java
+//SOURCES ../jabsrv/src/main/java/org/jabref/http/server/services/FilesToServe.java
+
+//REPOS mavencentral,mavencentralsnapshots=https://central.sonatype.com/repository/maven-snapshots/,s01oss=https://s01.oss.sonatype.org/content/repositories/snapshots/,oss=https://oss.sonatype.org/content/repositories,jitpack=https://jitpack.io,oss2=https://oss.sonatype.org/content/groups/public,ossrh=https://oss.sonatype.org/content/repositories/snapshots
+
+//DEPS org.jabref:jablib:6.+
+//DEPS info.picocli:picocli:4.7.7
+
+// from jabsrv
+//DEPS org.slf4j:slf4j-api:2.0.17
+//DEPS org.tinylog:slf4j-tinylog:2.7.0
+//DEPS org.tinylog:tinylog-impl:2.7.0
+//DEPS org.slf4j:jul-to-slf4j:2.0.17
+//DEPS org.apache.logging.log4j:log4j-to-slf4j:2.24.3
+//DEPS info.picocli:picocli:4.7.7
+//DEPS org.postgresql:postgresql:42.7.5
+//DEPS org.bouncycastle:bcprov-jdk18on:1.80
+//DEPS com.konghq:unirest-modules-gson:4.4.7
+//DEPS jakarta.ws.rs:jakarta.ws.rs-api:4.0.0
+//DEPS org.glassfish.jersey.core:jersey-server:3.1.10
+//DEPS org.glassfish.jersey.inject:jersey-hk2:3.1.10
+//DEPS org.glassfish.hk2:hk2-api:3.1.1
+//DEPS org.glassfish.hk2:hk2-utils:3.1.1
+//DEPS org.glassfish.hk2:hk2-locator:3.1.1
+//DEPS org.glassfish.jersey.containers:jersey-container-grizzly2-http:3.1.10
+//DEPS org.glassfish.grizzly:grizzly-http-server:4.0.2
+//DEPS org.glassfish.grizzly:grizzly-framework:4.0.2
+//DEPS jakarta.validation:jakarta.validation-api:3.1.1
+//DEPS org.hibernate.validator:hibernate-validator:8.0.2.Final
+//DEPS com.konghq:unirest-modules-gson:4.4.7
+//DEPS com.google.guava:guava:33.4.8-jre
+//DEPS org.jabref:afterburner.fx:2.0.0
+//DEPS net.harawata:appdirs:1.4.0
+//DEPS de.undercouch:citeproc-java:3.3.0
+
+/// This class is required for [jbang](https://www.jbang.dev/)
+public class JabSrvLauncher {
+    public static void main(String[] args) throws Exception {
+        org.jabref.http.server.cli.ServerCli.main(args);
+    }
+}

docs/code-howtos/http-server.md

@@ -10,20 +10,35 @@ The resource for a library is implemented at [`org.jabref.http.server.LibraryRes
 
 ## Start http server
 
+### Starting with IntelliJ
+
 The class starting the server is located in the project `jabsrv-cli` and is called `org.jabref.http.server.cli.ServerCli`.
 
 Test files to server can be passed as arguments.
-If no files are passed, the last opened files are served.
 If that list is also empty, the file `src/main/resources/org/jabref/http/server/http-server-demo.bib` is served.
 
+### Starting with JBang
+
+In case you want to interact only with the http server and do not want to set up or run IntelliJ, [JBang](https://www.jbang.dev/download/) can be used.
+
+In the repository root, run following command:
+
+```shell
+jbang .jbang/JabSrvLauncher.java
+```
+
+JBang also offers running without explicit installation, if you have node installed (and WSL available in the case of Windows):
+
+```shell
+npx @jbangdev/jbang .jbang/JabSrvLauncher.java
+```
+
 ### Starting with gradle
 
 ```shell
 ./gradlew run :jabsrv:run
 ```
 
-The GUI is also started. Just close it.
-
 Gradle output:
 
 ```shell
@@ -50,11 +65,19 @@ INFO: [HttpServer] Started.
 DEBUG: Server started.
 ```
 
+## Served libraries
+
+The last opened libraries are served.
+`demo` serves Chocolate.bib.
+Additional libraries can be served by passing them as arguments.
+
 ## Developing with IntelliJ
 
-IntelliJ Ultimate offers a Markdown-based http-client. One has to open the file `jabsrv/src/test/rest-api.http`.
+IntelliJ Ultimate offers a Markdown-based http-client. You need to open the file `jabsrv/src/test/rest-api.http`.
 Then, there are play buttons appearing for interacting with the server.
 
+In case you want to debug on Windows, you need to choose "WSL" as the target for the debugger ("Run on") to avoid "command line too long" errors.
+
 ## Get SSL Working
 
 When interacting with the [Microsoft Word AddIn](https://github.com/JabRef/JabRef-Word-Addin), a SSL-based connection is required.

jabsrv-cli/src/main/java/org/jabref/http/server/cli/ServerCli.java

@@ -1,8 +1,6 @@
 package org.jabref.http.server.cli;
 
 import java.net.URI;
-import java.net.URISyntaxException;
-import java.net.URL;
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
@@ -24,7 +22,7 @@
 public class ServerCli implements Callable<Void> {
     private static final Logger LOGGER = LoggerFactory.getLogger(ServerCli.class);
 
-    @CommandLine.Parameters(arity = "0..*", paramLabel = "FILE")
+    @CommandLine.Parameters(arity = "0..*", paramLabel = "FILE", description = "the library files (*.bib) to serve")
     List<Path> files;
 
     @CommandLine.Option(names = {"-h", "--host"}, description = "the host name")
@@ -46,11 +44,10 @@ public static void main(final String[] args) throws InterruptedException {
 
     @Override
     public Void call() throws InterruptedException {
+        // The server serves the last opened files (see org.jabref.http.server.LibraryResource.getLibraryPath)
         final List<Path> filesToServe = new ArrayList<>(JabRefCliPreferences.getInstance().getLastFilesOpenedPreferences().getLastFilesOpened());
 
-        // The server serves the last opened files (see org.jabref.http.server.LibraryResource.getLibraryPath)
-        // In a testing environment, this might be difficult to handle
-        // This is a quick solution. The architectural fine solution would use some http context or other @Inject_ed variables in org.jabref.http.server.LibraryResource
+        // Additionally, files can be provided as args
         if (files != null) {
             List<Path> filesToAdd = files.stream()
                                           .filter(Files::exists)
@@ -60,32 +57,11 @@ public Void call() throws InterruptedException {
             filesToServe.addAll(0, filesToAdd);
         }
 
-        if (filesToServe.isEmpty()) {
-            LOGGER.info("No library available to serve, serving the demo library...");
-            Path bibPath = null;
-            URL resource = Server.class.getResource("http-server-demo.bib");
-            if (resource != null) {
-                try {
-                    bibPath = Path.of(resource.toURI());
-                } catch (URISyntaxException e) {
-                    LOGGER.error("Error while converting URL to URI", e);
-                }
-            }
-            if (bibPath == null) {
-                // Server.class.getResource("...") is null when executing with IntelliJ
-                bibPath = Path.of("src/main/resources/org/jabref/http/server/http-server-demo.bib").toAbsolutePath();
-                if (Files.notExists(bibPath)) {
-                    bibPath = null;
-                    LOGGER.debug("http-server-demo.bib not found");
-                }
-            }
-
-            if (bibPath == null) {
-                LOGGER.info("No library to serve. Please provide a library file as argument.");
-            } else {
-                LOGGER.debug("Location of demo library: {}", bibPath);
-                filesToServe.add(bibPath);
-            }
+        // If we are on Windows and checked-out JabRef at the location given in the workspace setup guideline, we can serve Chocolate.bib, too
+        // Required by rest-api.http
+        Path exampleChocolateBib = Path.of("C:\\git-repositories\\JabRef\\jablib\\src\\main\\resources\\Chocolate.bib");
+        if (Files.exists(exampleChocolateBib)) {
+            filesToServe.add(exampleChocolateBib);
         }
 
         LOGGER.debug("Libraries to serve: {}", filesToServe);

jabsrv/src/main/java/org/jabref/http/server/LibrariesResource.java

@@ -1,5 +1,6 @@
 package org.jabref.http.server;
 
+import java.util.ArrayList;
 import java.util.List;
 
 import org.jabref.http.server.services.FilesToServe;
@@ -26,6 +27,8 @@ public String get() {
         List<String> fileNamesWithUniqueSuffix = filesToServe.getFilesToServe().stream()
                                                             .map(p -> p.getFileName() + "-" + BackupFileUtil.getUniqueFilePrefix(p))
                                                             .toList();
-        return gson.toJson(fileNamesWithUniqueSuffix);
+        List<String> result = new ArrayList<>(fileNamesWithUniqueSuffix);
+        result.add("demo");
+        return gson.toJson(result);
     }
 }

jabsrv/src/main/java/org/jabref/http/server/LibraryResource.java

@@ -1,6 +1,10 @@
 package org.jabref.http.server;
 
+import java.io.BufferedReader;
 import java.io.IOException;
+import java.io.InputStream;
+import java.io.InputStreamReader;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.util.List;
 import java.util.Objects;
@@ -13,6 +17,7 @@
 import org.jabref.logic.importer.fileformat.BibtexImporter;
 import org.jabref.logic.preferences.CliPreferences;
 import org.jabref.logic.util.io.BackupFileUtil;
+import org.jabref.model.database.BibDatabase;
 import org.jabref.model.entry.BibEntryTypesManager;
 import org.jabref.model.util.DummyFileUpdateMonitor;
 
@@ -27,6 +32,8 @@
 import jakarta.ws.rs.Produces;
 import jakarta.ws.rs.core.MediaType;
 import jakarta.ws.rs.core.Response;
+import jakarta.ws.rs.core.StreamingOutput;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
@@ -45,7 +52,7 @@ public class LibraryResource {
 
     @GET
     @Produces(MediaType.APPLICATION_JSON)
-    public String getJson(@PathParam("id") String id) {
+    public String getJson(@PathParam("id") String id) throws IOException {
         ParserResult parserResult = getParserResult(id);
         BibEntryTypesManager entryTypesManager = Injector.instantiateModelOrService(BibEntryTypesManager.class);
         List<BibEntryDTO> list = parserResult.getDatabase().getEntries().stream()
@@ -57,28 +64,29 @@ public String getJson(@PathParam("id") String id) {
 
     @GET
     @Produces(JabrefMediaType.JSON_CSL_ITEM)
-    public String getClsItemJson(@PathParam("id") String id) {
+    public String getClsItemJson(@PathParam("id") String id) throws IOException {
         ParserResult parserResult = getParserResult(id);
         JabRefItemDataProvider jabRefItemDataProvider = new JabRefItemDataProvider();
         jabRefItemDataProvider.setData(parserResult.getDatabaseContext(), new BibEntryTypesManager());
         return jabRefItemDataProvider.toJson();
     }
 
-    private ParserResult getParserResult(String id) {
-        java.nio.file.Path library = getLibraryPath(id);
-        ParserResult parserResult;
-        try {
-            parserResult = new BibtexImporter(preferences.getImportFormatPreferences(), new DummyFileUpdateMonitor()).importDatabase(library);
-        } catch (IOException e) {
-            LOGGER.warn("Could not find open library file {}", library, e);
-            throw new InternalServerErrorException("Could not parse library", e);
-        }
-        return parserResult;
-    }
-
     @GET
     @Produces(JabrefMediaType.BIBTEX)
     public Response getBibtex(@PathParam("id") String id) {
+        if ("demo".equals(id)) {
+            StreamingOutput stream = output -> {
+                try (InputStream in = getChocolateBibAsStream()) {
+                    in.transferTo(output);
+                }
+            };
+
+            return Response.ok(stream)
+                           // org.glassfish.jersey.media would be required for a "nice" Java to create ContentDisposition; we avoid this
+                           .header("Content-Disposition", "attachment; filename=\"Chocolate.bib\"")
+                           .build();
+        }
+
         java.nio.file.Path library = getLibraryPath(id);
         String libraryAsString;
         try {
@@ -88,6 +96,7 @@ public Response getBibtex(@PathParam("id") String id) {
             throw new InternalServerErrorException("Could not read library " + library, e);
         }
         return Response.ok()
+                .header("Content-Disposition", "attachment; filename=\"" + library.getFileName() + "\"")
                 .entity(libraryAsString)
                 .build();
     }
@@ -99,4 +108,30 @@ private java.nio.file.Path getLibraryPath(String id) {
                           .findAny()
                           .orElseThrow(NotFoundException::new);
     }
+
+    private ParserResult getParserResult(String id) throws IOException {
+        BibtexImporter bibtexImporter = new BibtexImporter(preferences.getImportFormatPreferences(), new DummyFileUpdateMonitor());
+
+        if ("demo".equals(id)) {
+            try (InputStream chocolateBibInputStream = getChocolateBibAsStream()) {
+                BufferedReader reader = new BufferedReader(new InputStreamReader(chocolateBibInputStream, StandardCharsets.UTF_8));
+                return bibtexImporter.importDatabase(reader);
+            }
+        }
+
+        java.nio.file.Path library = getLibraryPath(id);
+        ParserResult parserResult;
+        try {
+            parserResult = bibtexImporter.importDatabase(library);
+        } catch (IOException e) {
+            LOGGER.warn("Could not find open library file {}", library, e);
+            throw new InternalServerErrorException("Could not parse library", e);
+        }
+        return parserResult;
+    }
+
+    /// @return a stream to the Chocolate.bib file in the classpath (is null only if the file was moved or there are issues with the classpath)
+    private @Nullable InputStream getChocolateBibAsStream() {
+        return BibDatabase.class.getResourceAsStream("/Chocolate.bib");
+    }
 }

jabsrv/src/test/java/org/jabref/http/server/LibrariesResourceTest.java

@@ -23,8 +23,9 @@ protected Application configure() {
     void defaultOneTestLibrary() {
         String expected = """
                 [
+                  "%s",
                   "%s"
-                ]""".formatted(TestBibFile.GENERAL_SERVER_TEST.id);
+                ]""".formatted(TestBibFile.GENERAL_SERVER_TEST.id, "demo");
         assertEquals(expected, target("/libraries").request().get(String.class));
     }
 
@@ -35,9 +36,10 @@ void twoTestLibraries() {
 
         String expected = """
                 [
+                  "%s",
                   "%s",
                   "%s"
-                ]""".formatted(TestBibFile.GENERAL_SERVER_TEST.id, TestBibFile.CHOCOLATE_BIB.id);
+                ]""".formatted(TestBibFile.GENERAL_SERVER_TEST.id, TestBibFile.CHOCOLATE_BIB.id, "demo");
         assertEquals(expected, target("/libraries").request().get(String.class));
     }
 }