SyncServer: simplify docs, improve JWT options naming and checks #252

Author: greenrobot-team

objectbox-java/src/main/java/io/objectbox/sync/Sync.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -90,17 +90,8 @@ public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCreden
     }
 
     /**
-     * Starts building a {@link SyncServer}. Once done, complete with {@link SyncServerBuilder#build() build()}.
-     * <p>
-     * Note: when also using Admin, make sure it is started before the server.
-     *
-     * @param boxStore The {@link BoxStore} the server should use.
-     * @param url The URL of the Sync server on which the Sync protocol is exposed. This is typically a WebSockets URL
-     * starting with {@code ws://} or {@code wss://} (for encrypted connections), for example
-     * {@code ws://0.0.0.0:9999}.
-     * @param multipleAuthenticatorCredentials An authentication method available to Sync clients and peers. Additional
-     * authenticator credentials can be supplied using the returned builder. For the embedded server, currently only
-     * {@link SyncCredentials#sharedSecret} and {@link SyncCredentials#none} are supported.
+     * Like {@link #server(BoxStore, String, SyncCredentials)}, but supports passing a set of authentication methods
+     * for clients and peers.
      */
     public static SyncServerBuilder server(BoxStore boxStore, String url, SyncCredentials[] multipleAuthenticatorCredentials) {
         return new SyncServerBuilder(boxStore, url, multipleAuthenticatorCredentials);

objectbox-java/src/main/java/io/objectbox/sync/server/SyncServerBuilder.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2019-2024 ObjectBox Ltd. All rights reserved.
+ * Copyright 2019-2025 ObjectBox Ltd. All rights reserved.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -55,10 +55,10 @@ public final class SyncServerBuilder {
     private int syncServerFlags;
     private int workerThreads;
 
-    private String publicKey;
-    private String publicKeyUrl;
-    private String claimIss;
-    private String claimAud;
+    private @Nullable String jwtPublicKey;
+    private @Nullable String jwtPublicKeyUrl;
+    private @Nullable String jwtClaimIss;
+    private @Nullable String jwtClaimAud;
 
     private static void checkFeatureSyncServerAvailable() {
         if (!BoxStore.isSyncServerAvailable()) {
@@ -273,39 +273,43 @@ public SyncServerBuilder workerThreads(int workerThreads) {
     }
 
     /**
-     * Set the public key used to verify JWT tokens.
+     * Sets the public key used to verify JWT tokens.
      * <p>
      * The public key should be in the PEM format.
      */
     public SyncServerBuilder jwtConfigPublicKey(String publicKey) {
-        this.publicKey = publicKey;
+        this.jwtPublicKey = publicKey;
         return this;
     }
 
     /**
-     * Set the JWKS (Json Web Key Sets) URL to fetch the current public key used to verify JWT tokens.
+     * Sets the JWKS (Json Web Key Sets) URL to fetch the current public key used to verify JWT tokens.
      */
     public SyncServerBuilder jwtConfigPublicKeyUrl(String publicKeyUrl) {
-        this.publicKeyUrl = publicKeyUrl;
+        this.jwtPublicKeyUrl = publicKeyUrl;
         return this;
     }
 
     /**
-     * Set the JWT claim "iss" (issuer) used to verify JWT tokens.
+     * Sets the JWT claim "iss" (issuer) used to verify JWT tokens.
      */
     public SyncServerBuilder jwtConfigClaimIss(String claimIss) {
-        this.claimIss = claimIss;
+        this.jwtClaimIss = claimIss;
         return this;
     }
 
     /**
-     * Set the JWT claim "aud" (audience) used to verify JWT tokens.
+     * Sets the JWT claim "aud" (audience) used to verify JWT tokens.
      */
     public SyncServerBuilder jwtConfigClaimAud(String claimAud) {
-        this.claimAud = claimAud;
+        this.jwtClaimAud = claimAud;
         return this;
     }
 
+    private boolean hasJwtConfig() {
+        return jwtPublicKey != null || jwtPublicKeyUrl != null;
+    }
+
     /**
      * Builds and returns a Sync server ready to {@link SyncServer#start()}.
      * <p>
@@ -315,6 +319,14 @@ public SyncServer build() {
         if (credentials.isEmpty()) {
             throw new IllegalStateException("At least one authenticator is required.");
         }
+        if (hasJwtConfig()) {
+            if (jwtClaimAud == null) {
+                throw new IllegalArgumentException("To use JWT authentication, claimAud must be set");
+            }
+            if (jwtClaimIss == null) {
+                throw new IllegalArgumentException("To use JWT authentication, claimIss must be set");
+            }
+        }
         if (!clusterPeers.isEmpty() || clusterFlags != 0) {
             checkNotNull(clusterId, "Cluster ID must be set to use cluster features.");
         }
@@ -359,14 +371,8 @@ byte[] buildSyncServerOptions() {
         int authenticationMethodsOffset = buildAuthenticationMethods(fbb);
         int clusterPeersVectorOffset = buildClusterPeers(fbb);
         int jwtConfigOffset = 0;
-        if (publicKey != null || publicKeyUrl != null) {
-            if (claimAud == null) {
-                throw new IllegalArgumentException("claimAud must be set");
-            }
-            if (claimIss == null) {
-                throw new IllegalArgumentException("claimIss must be set");
-            }
-            jwtConfigOffset = buildJwtConfig(fbb, publicKey, publicKeyUrl, claimIss, claimAud);
+        if (hasJwtConfig()) {
+            jwtConfigOffset = buildJwtConfig(fbb, jwtPublicKey, jwtPublicKeyUrl, jwtClaimIss, jwtClaimAud);
         }
         // Clear credentials immediately to make abuse less likely,
         // but only after setting all options to allow (re-)using the same credentials object