Merge branch 'master' into feat-json-column-type-sql-view

Author: jason-p-pickering

.github/workflows/performance-tests.yml

@@ -332,7 +332,7 @@ jobs:
 
     - name: Send Slack notification on failure
       if: failure() && steps.check_slack.outputs.webhook_configured == 'true'
-      uses: slackapi/slack-github-action@v3.0.2
+      uses: slackapi/slack-github-action@v3.0.3
       with:
         webhook: ${{ secrets.slack_webhook }}
         webhook-type: incoming-webhook

dhis-2/dhis-api/src/main/java/org/hisp/dhis/configuration/ConfigurationService.java

@@ -29,6 +29,7 @@
  */
 package org.hisp.dhis.configuration;
 
+import java.util.Set;
 import org.hisp.dhis.user.UserDetails;
 
 /**
@@ -51,6 +52,23 @@ public interface ConfigurationService {
    */
   Configuration getConfiguration();
 
+  /**
+   * Returns the configured CORS whitelist. The result is cached for fast read access on hot paths
+   * (CORS preflight checks, CSP {@code frame-ancestors} composition); the cache is invalidated by
+   * {@link #setCorsWhitelist(Set)}.
+   *
+   * @return the whitelist (never {@code null}).
+   */
+  Set<String> getCorsWhitelist();
+
+  /**
+   * Replaces the CORS whitelist and invalidates the read cache populated by {@link
+   * #getCorsWhitelist()}.
+   *
+   * @param corsWhitelist the new whitelist (may be empty, must not be {@code null}).
+   */
+  void setCorsWhitelist(Set<String> corsWhitelist);
+
   /**
    * Indicates whether the given origin is CORS white listed.
    *

dhis-2/dhis-api/src/main/java/org/hisp/dhis/metadata/version/MetadataVersionService.java

@@ -29,6 +29,8 @@
  */
 package org.hisp.dhis.metadata.version;
 
+import java.io.IOException;
+import java.io.OutputStream;
 import java.util.Date;
 import java.util.List;
 
@@ -128,12 +130,27 @@ public interface MetadataVersionService {
   boolean saveVersion(VersionType versionType);
 
   /**
-   * Gets the Version data - the actual JSON snapshot given the version name.
+   * Streams the metadata snapshot for the given version name directly to the output stream.
    *
-   * @param versionName
-   * @return JSON data for the version snapshot
+   * <p>Scans the stored JSONB wrapper directly without materialising a full Java String copy of the
+   * metadata field, which is a more memory-efficient path for large snapshots.
+   *
+   * @param versionName the version name
+   * @param out the output stream to write the snapshot to
+   * @return true if the snapshot was found and written, false if no snapshot exists
+   * @throws IOException if writing to the output stream fails
+   */
+  boolean streamVersionData(String versionName, OutputStream out) throws IOException;
+
+  /**
+   * Returns whether a metadata snapshot exists for the given version name. Cheap pre-flight check
+   * intended to be called before opening any response output stream — see {@link
+   * MetadataVersionStore#metadataVersionSnapshotExists} for the rationale.
+   *
+   * @param versionName the version name
+   * @return true if a snapshot is stored for that version
    */
-  String getVersionData(String versionName);
+  boolean snapshotExists(String versionName);
 
   /**
    * Creates an entry in the DataStore given the MetadataVersion details.

dhis-2/dhis-api/src/main/java/org/hisp/dhis/metadata/version/MetadataVersionStore.java

@@ -29,6 +29,8 @@
  */
 package org.hisp.dhis.metadata.version;
 
+import java.io.IOException;
+import java.io.OutputStream;
 import java.util.Date;
 import java.util.List;
 import org.hisp.dhis.common.GenericStore;
@@ -75,4 +77,29 @@ public interface MetadataVersionStore extends GenericStore<MetadataVersion> {
    * @return Initial/First MetadataVersion of the system
    */
   MetadataVersion getInitialVersion();
+
+  /**
+   * Streams the metadata snapshot for the given version name directly from the underlying datastore
+   * row to the output stream. Avoids materialising the snapshot as a Java String, which is
+   * memory-prohibitive for large snapshots and would also trip Jackson's default 20MB string-token
+   * limit during deserialisation of the wrapper object.
+   *
+   * @param versionName the version name
+   * @param out the output stream to write the snapshot to
+   * @return true if the snapshot was found and written, false if no snapshot exists
+   * @throws IOException if writing to the output stream fails
+   */
+  boolean streamMetadataVersionData(String versionName, OutputStream out) throws IOException;
+
+  /**
+   * Returns whether a metadata snapshot exists for the given version name. Intended as a cheap
+   * pre-flight check before opening a response output stream — once {@link
+   * #streamMetadataVersionData} starts writing, response headers are committed and an error status
+   * can no longer be returned to the client (especially relevant for the gzipped variant where
+   * {@code GZIPOutputStream} writes its magic header on construction).
+   *
+   * @param versionName the version name
+   * @return true if a snapshot row exists in the metadata datastore namespace
+   */
+  boolean metadataVersionSnapshotExists(String versionName);
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/security/oauth2/OAuth2GrantTypes.java

@@ -35,6 +35,11 @@
 /**
  * Shared helpers for Spring Authorization Server {@link AuthorizationGrantType} values.
  *
+ * <p>Used by {@code Dhis2OAuth2ClientServiceImpl} when building a Spring AS {@link
+ * org.springframework.security.oauth2.server.authorization.client.RegisteredClient} from a
+ * persisted {@link org.hisp.dhis.security.oauth2.client.Dhis2OAuth2Client}, where the stored
+ * grant-type strings need to be resolved back to Spring's typed constants.
+ *
  * @author Morten Svanæs <msvanaes@dhis2.org>
  */
 public final class OAuth2GrantTypes {
@@ -44,7 +49,7 @@ private OAuth2GrantTypes() {}
   /**
    * Map a grant-type string back to Spring's canonical {@link AuthorizationGrantType} singleton
    * (authorization_code, client_credentials, refresh_token, device_code). Falls back to a new
-   * instance for any custom value — the equality contract on {@code AuthorizationGrantType} is
+   * instance for any custom value. The equality contract on {@code AuthorizationGrantType} is
    * value-based, but returning the singleton where possible keeps identity comparisons working.
    *
    * <p>Case labels are the RFC-defined grant-type strings (RFC 6749 + RFC 8628); they match

dhis-2/dhis-api/src/main/java/org/hisp/dhis/security/oauth2/authorization/Dhis2OAuth2Authorization.java

@@ -62,6 +62,8 @@
  * /api/metadata} export; token-bearing fields are additionally {@link JsonIgnore}'d so no REST
  * surface can leak them even on explicit requests. Persistence uses Hibernate field access ({@code
  * Dhis2OAuth2Authorization.hbm.xml}) and is independent of the JSON annotations.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
  */
 @Getter
 @Setter
@@ -73,11 +75,32 @@ public class Dhis2OAuth2Authorization extends BaseIdentifiableObject
   /** Required by Hibernate + Jackson for reflective instantiation. */
   public Dhis2OAuth2Authorization() {}
 
+  /**
+   * Reference to the {@link org.hisp.dhis.security.oauth2.client.Dhis2OAuth2Client} this grant was
+   * issued to. Holds the internal id of the registered client, not its public {@code clientId}.
+   */
   @JsonProperty private String registeredClientId;
+
+  /**
+   * Name of the resource owner the grant is tied to. For user-delegated flows this is the DHIS2
+   * username; for {@code client_credentials} it is the client itself.
+   */
   @JsonProperty private String principalName;
+
+  /**
+   * The grant type that produced this authorization (e.g. {@code authorization_code}, {@code
+   * client_credentials}, {@code refresh_token}, {@code
+   * urn:ietf:params:oauth:grant-type:device_code}).
+   */
   @JsonProperty private String authorizationGrantType;
+
+  /** Comma-separated list of scopes that were actually granted for this authorization. */
   @JsonProperty private String authorizedScopes;
+
+  /** JSON-encoded Spring AS attributes map (authenticated principal, request metadata, etc.). */
   @JsonIgnore private String attributes;
+
+  /** Opaque {@code state} value used by Spring AS for OAuth2 CSRF protection during the flow. */
   @JsonIgnore private String state;
 
   @JsonIgnore private String authorizationCodeValue;

dhis-2/dhis-api/src/main/java/org/hisp/dhis/security/oauth2/authorization/Dhis2OAuth2AuthorizationStore.java

@@ -33,7 +33,19 @@
 import javax.annotation.Nonnull;
 import org.hisp.dhis.common.IdentifiableObjectStore;
 
-/** Store for OAuth2Authorization entities. */
+/**
+ * Persistence store for {@link Dhis2OAuth2Authorization}. These lookup methods back Spring
+ * Authorization Server's {@link
+ * org.springframework.security.oauth2.server.authorization.OAuth2AuthorizationService}
+ * implementation, in particular its {@code findByToken(String, OAuth2TokenType)} contract.
+ *
+ * <p>{@link #getByToken(String)} has union semantics: it searches across every token column on
+ * {@link Dhis2OAuth2Authorization} (authorization code, access token, refresh token, OIDC ID token,
+ * user code, device code) and returns the first matching row, which is what Spring AS needs when
+ * asked to resolve a token without knowing its type up-front.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
+ */
 public interface Dhis2OAuth2AuthorizationStore
     extends IdentifiableObjectStore<Dhis2OAuth2Authorization> {
 

dhis-2/dhis-api/src/main/java/org/hisp/dhis/security/oauth2/client/Dhis2OAuth2Client.java

@@ -38,6 +38,26 @@
 import org.hisp.dhis.common.DxfNamespaces;
 import org.hisp.dhis.common.MetadataObject;
 
+/**
+ * Persisted OAuth2 registered-client entity. Mirrors Spring Authorization Server's {@link
+ * org.springframework.security.oauth2.server.authorization.client.RegisteredClient}, mapped to the
+ * {@code oauth2_client} table, and is the DB row that authorizes an app to request tokens from
+ * DHIS2 acting as an Authorization Server.
+ *
+ * <p>Exposed via the admin CRUD endpoints under {@code /api/oAuth2Clients}, gated by the {@code
+ * F_OAUTH2_CLIENT_MANAGE} authority. Clients can also be created dynamically via the Dynamic Client
+ * Registration (RFC 7591) endpoint {@code /connect/register}.
+ *
+ * <p>Several fields are stored as comma-separated strings (for example {@link
+ * #authorizationGrantTypes}, {@link #clientAuthenticationMethods}, {@link #redirectUris}, {@link
+ * #postLogoutRedirectUris}, {@link #scopes}) and are parsed into Spring AS's typed values (e.g.
+ * {@link org.springframework.security.oauth2.core.AuthorizationGrantType}, {@link
+ * org.springframework.security.oauth2.core.ClientAuthenticationMethod}) by {@code
+ * Dhis2OAuth2ClientServiceImpl.toObject} when building a {@link
+ * org.springframework.security.oauth2.server.authorization.client.RegisteredClient}.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
+ */
 @Getter
 @Setter
 @JacksonXmlRootElement(localName = "oauth2Client", namespace = DxfNamespaces.DXF_2_0)
@@ -49,7 +69,7 @@ public Dhis2OAuth2Client() {}
    * Override so that the persisted {@code name} column is always populated even if the caller (the
    * settings UI, which has no name field) doesn't supply one. Hibernate uses property access for
    * this entity, so the value returned here is what gets written to the DB and what the schema
-   * validator at {@code POST /api/schemas/oAuth2Client} reads via reflection — letting us keep
+   * validator at {@code POST /api/schemas/oAuth2Client} reads via reflection, letting us keep
    * {@code not-null="true"} on the column without breaking UI pre-validation. Truncated to the
    * column length (230) so the schema-validator's {@code @PropertyRange} check on a long {@code
    * clientId} (max 255) doesn't reject the request.
@@ -75,15 +95,65 @@ public String getRawName() {
     return super.getName();
   }
 
+  /**
+   * Public OAuth2 {@code client_id} presented by the client at the token and authorize endpoints.
+   */
   @JsonProperty private String clientId;
+
+  /**
+   * Client secret used for the {@code client_secret_basic} / {@code client_secret_post}
+   * authentication methods. Stored hashed; null for public clients and for clients that
+   * authenticate via {@code private_key_jwt}.
+   */
   @JsonProperty private String clientSecret;
+
+  /** Timestamp at which {@link #clientId} was issued. */
   @JsonProperty private Date clientIdIssuedAt;
+
+  /** Optional expiry for {@link #clientSecret}; null means the secret does not expire. */
   @JsonProperty private Date clientSecretExpiresAt;
+
+  /**
+   * Comma-separated list of OAuth2 client authentication methods the client may use at the token
+   * endpoint (e.g. {@code client_secret_basic}, {@code client_secret_post}, {@code
+   * private_key_jwt}, {@code none}). Parsed into Spring AS {@link
+   * org.springframework.security.oauth2.core.ClientAuthenticationMethod} values at load time.
+   */
   @JsonProperty private String clientAuthenticationMethods;
+
+  /**
+   * Comma-separated list of OAuth2 authorization grant types the client is permitted to use (e.g.
+   * {@code authorization_code}, {@code client_credentials}, {@code refresh_token}, {@code
+   * urn:ietf:params:oauth:grant-type:device_code}). Parsed into Spring AS {@link
+   * org.springframework.security.oauth2.core.AuthorizationGrantType} values via {@link
+   * org.hisp.dhis.security.oauth2.OAuth2GrantTypes#resolve(String)}.
+   */
   @JsonProperty private String authorizationGrantTypes;
+
+  /**
+   * Comma-separated list of registered redirect URIs used by the authorization-code and device-code
+   * flows; an incoming {@code redirect_uri} must match one of these exactly.
+   */
   @JsonProperty private String redirectUris;
+
+  /** Comma-separated list of post-logout redirect URIs allowed after OIDC RP-initiated logout. */
   @JsonProperty private String postLogoutRedirectUris;
+
+  /**
+   * Comma-separated list of OAuth2 / OpenID Connect scopes (e.g. {@code openid}, {@code profile},
+   * {@code email}) the client is permitted to request.
+   */
   @JsonProperty private String scopes;
+
+  /**
+   * JSON-encoded Spring AS {@code ClientSettings}; controls client-level options such as whether
+   * user consent is required and PKCE requirements.
+   */
   @JsonProperty private String clientSettings;
+
+  /**
+   * JSON-encoded Spring AS {@code TokenSettings}; controls token lifetimes, access-token format
+   * (opaque vs JWT), refresh-token behavior and ID-token signature algorithm.
+   */
   @JsonProperty private String tokenSettings;
 }

dhis-2/dhis-api/src/main/java/org/hisp/dhis/security/oauth2/client/Dhis2OAuth2ClientStore.java

@@ -33,7 +33,13 @@
 import javax.annotation.Nonnull;
 import org.hisp.dhis.common.IdentifiableObjectStore;
 
-/** Store for OAuth2Client entities. */
+/**
+ * Persistence store for {@link Dhis2OAuth2Client}. Used by the authorization server's {@link
+ * org.springframework.security.oauth2.server.authorization.client.RegisteredClientRepository}
+ * implementation to load clients at token-endpoint time.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
+ */
 public interface Dhis2OAuth2ClientStore extends IdentifiableObjectStore<Dhis2OAuth2Client> {
 
   /**

dhis-2/dhis-api/src/main/java/org/hisp/dhis/security/oauth2/consent/Dhis2OAuth2AuthorizationConsent.java

@@ -60,6 +60,8 @@
  * <p>Marked {@link SecondaryMetadataObject} so the type is excluded from the default {@code
  * /api/metadata} export. Persistence uses Hibernate field access ({@code
  * Dhis2OAuth2AuthorizationConsent.hbm.xml}) and is independent of the JSON annotations.
+ *
+ * @author Morten Svanæs <msvanaes@dhis2.org>
  */
 @Getter
 @Setter