diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 000000000..01d42e740 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,45 @@ +name: CI + +on: + pull_request: + push: + branches: + - main + workflow_dispatch: + +concurrency: + group: ci-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +permissions: + contents: read + +jobs: + server-test: + name: Server tests + runs-on: ubuntu-24.04 + defaults: + run: + working-directory: server + steps: + - name: Checkout repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + + - name: Install Java 21 + uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0 + with: + distribution: temurin + java-version: "21" + cache: maven + cache-dependency-path: server/pom.xml + + - name: Run tests + run: mvn -B -ntp verify + + - name: Upload test reports + if: failure() + uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2 + with: + name: surefire-reports + path: server/target/surefire-reports/ + if-no-files-found: ignore diff --git a/server/.gitignore b/server/.gitignore new file mode 100644 index 000000000..79bee1ea3 --- /dev/null +++ b/server/.gitignore @@ -0,0 +1,5 @@ +target/ +data/ +*.db +*.mv.db +*.trace.db diff --git a/server/README.md b/server/README.md new file mode 100644 index 000000000..537aabee3 --- /dev/null +++ b/server/README.md @@ -0,0 +1,10 @@ +# OpenSharing Reference Server + +Reference implementation of the [OpenSharing](https://github.com/OpenSharing-IO/OpenSharing) protocol. + +## Build + +```bash +cd server +mvn test +``` diff --git a/server/pom.xml b/server/pom.xml new file mode 100644 index 000000000..72e1d55fa --- /dev/null +++ b/server/pom.xml @@ -0,0 +1,104 @@ + + + 4.0.0 + + io.opensharing + opensharing-server + 0.1.0-SNAPSHOT + + OpenSharing Reference Server + Reference implementation of the OpenSharing protocol + + + + Apache License, Version 2.0 + https://www.apache.org/licenses/LICENSE-2.0 + + + + + UTF-8 + 21 + 3.5.3 + + + + + + org.springframework.boot + spring-boot-dependencies + ${spring-boot.version} + pom + import + + + + + + + org.springframework.boot + spring-boot-starter-web + + + org.springframework.boot + spring-boot-starter-data-jpa + + + org.springframework.boot + spring-boot-starter-validation + + + org.springframework.boot + spring-boot-configuration-processor + true + + + com.fasterxml.jackson.dataformat + jackson-dataformat-yaml + + + com.h2database + h2 + runtime + + + org.springframework.boot + spring-boot-starter-test + test + + + + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.13.0 + + + -parameters + + + + + org.apache.maven.plugins + maven-surefire-plugin + 3.2.5 + + + org.springframework.boot + spring-boot-maven-plugin + ${spring-boot.version} + + + + repackage + + + + + + + diff --git a/server/src/main/java/io/opensharing/BaseEntity.java b/server/src/main/java/io/opensharing/BaseEntity.java new file mode 100644 index 000000000..2a0aa417e --- /dev/null +++ b/server/src/main/java/io/opensharing/BaseEntity.java @@ -0,0 +1,55 @@ +package io.opensharing; + +import jakarta.persistence.Column; +import jakarta.persistence.Id; +import jakarta.persistence.MappedSuperclass; +import jakarta.persistence.PrePersist; +import jakarta.persistence.PreUpdate; +import java.time.Instant; +import java.util.UUID; + +/** Server-assigned identity and audit columns shared by every stored entity. */ +@MappedSuperclass +public abstract class BaseEntity { + + @Id + @Column(name = "id", length = 36, nullable = false, updatable = false) + private String id = UUID.randomUUID().toString(); + + @Column(name = "created_at", nullable = false, updatable = false) + private Instant createdAt; + + @Column(name = "updated_at", nullable = false) + private Instant updatedAt; + + @PrePersist + void onPersist() { + this.createdAt = Instant.now(); + this.updatedAt = this.createdAt; + } + + @PreUpdate + void onUpdate() { + this.updatedAt = Instant.now(); + } + + public String getId() { + return id; + } + + /** + * Adopts an id chosen elsewhere, for the entities whose identity is not the server's to invent. Only + * meaningful before the row is written: the column is not updatable. + */ + protected void setId(String id) { + this.id = id; + } + + public Instant getCreatedAt() { + return createdAt; + } + + public Instant getUpdatedAt() { + return updatedAt; + } +} diff --git a/server/src/main/java/io/opensharing/ObjectNames.java b/server/src/main/java/io/opensharing/ObjectNames.java new file mode 100644 index 000000000..e257dadf5 --- /dev/null +++ b/server/src/main/java/io/opensharing/ObjectNames.java @@ -0,0 +1,69 @@ +package io.opensharing; + +import java.util.Locale; + +/** + * Name rules from {@code spec/protocols/OVERVIEW.md}. Object names are compared case-insensitively, + * so callers persist {@link #normalize(String)} alongside the name as provided. + */ +public final class ObjectNames { + + public static final int MAX_LENGTH = 255; + + private ObjectNames() {} + + /** Validates a share name. */ + public static String validateShareName(String name) { + return validate(name, "share name", false); + } + + /** Validates a schema name, which additionally disallows {@code .}. */ + public static String validateSchemaName(String name) { + return validate(name, "schema name", true); + } + + /** Validates a shared asset name, which additionally disallows {@code .}. */ + public static String validateAssetName(String name) { + return validate(name, "asset name", true); + } + + /** Validates a recipient name using the same rules as a share name. */ + public static String validateRecipientName(String name) { + return validate(name, "recipient name", false); + } + + /** Validates a principal name, which is often an email address and so may contain periods. */ + public static String validatePrincipalName(String name) { + return validate(name, "principal name", false); + } + + /** Lower-cases a name for case-insensitive lookups and uniqueness checks. */ + public static String normalize(String name) { + return name == null ? null : name.toLowerCase(Locale.ROOT); + } + + private static String validate(String name, String what, boolean rejectPeriod) { + if (name == null || name.isEmpty()) { + throw new IllegalArgumentException(what + " must not be empty"); + } + if (name.length() > MAX_LENGTH) { + throw new IllegalArgumentException(what + " must not exceed " + MAX_LENGTH + " characters"); + } + for (int i = 0; i < name.length(); i++) { + char c = name.charAt(i); + if (c == ' ') { + throw new IllegalArgumentException(what + " must not contain a space"); + } + if (c == '/') { + throw new IllegalArgumentException(what + " must not contain a forward slash"); + } + if (c <= 0x1F || c == 0x7F) { + throw new IllegalArgumentException(what + " must not contain control characters"); + } + if (rejectPeriod && c == '.') { + throw new IllegalArgumentException(what + " must not contain a period"); + } + } + return name; + } +} diff --git a/server/src/main/java/io/opensharing/OpenSharingServer.java b/server/src/main/java/io/opensharing/OpenSharingServer.java new file mode 100644 index 000000000..b972ae751 --- /dev/null +++ b/server/src/main/java/io/opensharing/OpenSharingServer.java @@ -0,0 +1,12 @@ +package io.opensharing; + +import org.springframework.boot.SpringApplication; +import org.springframework.boot.autoconfigure.SpringBootApplication; + +@SpringBootApplication +public class OpenSharingServer { + + public static void main(String[] args) { + SpringApplication.run(OpenSharingServer.class, args); + } +} diff --git a/server/src/main/java/io/opensharing/http/AdminJson.java b/server/src/main/java/io/opensharing/http/AdminJson.java new file mode 100644 index 000000000..1d121f8ae --- /dev/null +++ b/server/src/main/java/io/opensharing/http/AdminJson.java @@ -0,0 +1,19 @@ +package io.opensharing.http; + +import com.fasterxml.jackson.annotation.JacksonAnnotationsInside; +import com.fasterxml.jackson.databind.PropertyNamingStrategies; +import com.fasterxml.jackson.databind.annotation.JsonNaming; +import java.lang.annotation.ElementType; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; +import java.lang.annotation.Target; + +/** + * Marks a provider-admin request or response body. The admin API speaks snake_case, unlike the + * recipient-facing protocol, which is camelCase and must stay that way for Delta Sharing clients. + */ +@JacksonAnnotationsInside +@JsonNaming(PropertyNamingStrategies.SnakeCaseStrategy.class) +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.TYPE) +public @interface AdminJson {} diff --git a/server/src/main/java/io/opensharing/http/ApiException.java b/server/src/main/java/io/opensharing/http/ApiException.java new file mode 100644 index 000000000..76ad725f6 --- /dev/null +++ b/server/src/main/java/io/opensharing/http/ApiException.java @@ -0,0 +1,54 @@ +package io.opensharing.http; + +import org.springframework.http.HttpStatus; + +/** An error with an explicit protocol error code and HTTP status. */ +public class ApiException extends RuntimeException { + + private final HttpStatus status; + private final String errorCode; + + public ApiException(HttpStatus status, String errorCode, String message) { + super(message); + this.status = status; + this.errorCode = errorCode; + } + + public HttpStatus getStatus() { + return status; + } + + public String getErrorCode() { + return errorCode; + } + + public static ApiException notFound(String message) { + return new ApiException(HttpStatus.NOT_FOUND, ErrorCodes.RESOURCE_DOES_NOT_EXIST, message); + } + + public static ApiException alreadyExists(String message) { + return new ApiException(HttpStatus.CONFLICT, ErrorCodes.RESOURCE_ALREADY_EXISTS, message); + } + + /** The object exists, but its current state does not allow what was asked. */ + public static ApiException conflict(String message) { + return new ApiException(HttpStatus.CONFLICT, ErrorCodes.RESOURCE_CONFLICT, message); + } + + public static ApiException invalidParameter(String message) { + return new ApiException(HttpStatus.BAD_REQUEST, ErrorCodes.INVALID_PARAMETER_VALUE, message); + } + + /** The caller is known, but is not allowed to do this. */ + public static ApiException permissionDenied(String message) { + return new ApiException(HttpStatus.FORBIDDEN, ErrorCodes.PERMISSION_DENIED, message); + } + + public static ApiException unauthenticated(String message) { + return new ApiException(HttpStatus.UNAUTHORIZED, ErrorCodes.UNAUTHENTICATED, message); + } + + public static ApiException notImplemented(String message) { + return new ApiException(HttpStatus.NOT_IMPLEMENTED, ErrorCodes.NOT_IMPLEMENTED, message); + } +} diff --git a/server/src/main/java/io/opensharing/http/ErrorCodes.java b/server/src/main/java/io/opensharing/http/ErrorCodes.java new file mode 100644 index 000000000..09614b1cd --- /dev/null +++ b/server/src/main/java/io/opensharing/http/ErrorCodes.java @@ -0,0 +1,18 @@ +package io.opensharing.http; + +/** Error codes used in {@link ErrorResponse#errorCode()}. */ +public final class ErrorCodes { + + public static final String MALFORMED_REQUEST = "MALFORMED_REQUEST"; + public static final String INVALID_PARAMETER_VALUE = "INVALID_PARAMETER_VALUE"; + public static final String UNAUTHENTICATED = "UNAUTHENTICATED"; + public static final String PERMISSION_DENIED = "PERMISSION_DENIED"; + public static final String RESOURCE_DOES_NOT_EXIST = "RESOURCE_DOES_NOT_EXIST"; + public static final String RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS"; + public static final String RESOURCE_CONFLICT = "RESOURCE_CONFLICT"; + public static final String CATALOG_ERROR = "CATALOG_ERROR"; + public static final String NOT_IMPLEMENTED = "NOT_IMPLEMENTED"; + public static final String INTERNAL_ERROR = "INTERNAL_ERROR"; + + private ErrorCodes() {} +} diff --git a/server/src/main/java/io/opensharing/http/ErrorResponse.java b/server/src/main/java/io/opensharing/http/ErrorResponse.java new file mode 100644 index 000000000..aea36ae13 --- /dev/null +++ b/server/src/main/java/io/opensharing/http/ErrorResponse.java @@ -0,0 +1,4 @@ +package io.opensharing.http; + +/** Error body returned by every non-2xx protocol response. */ +public record ErrorResponse(String errorCode, String message) {} diff --git a/server/src/main/java/io/opensharing/http/GlobalExceptionHandler.java b/server/src/main/java/io/opensharing/http/GlobalExceptionHandler.java new file mode 100644 index 000000000..84b75d355 --- /dev/null +++ b/server/src/main/java/io/opensharing/http/GlobalExceptionHandler.java @@ -0,0 +1,82 @@ +package io.opensharing.http; + +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.dao.DataIntegrityViolationException; +import org.springframework.http.HttpStatus; +import org.springframework.http.ResponseEntity; +import org.springframework.http.converter.HttpMessageNotReadableException; +import org.springframework.web.bind.MethodArgumentNotValidException; +import org.springframework.web.bind.annotation.ExceptionHandler; +import org.springframework.web.bind.annotation.RestControllerAdvice; +import org.springframework.web.method.annotation.HandlerMethodValidationException; +import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException; +import org.springframework.web.servlet.resource.NoResourceFoundException; + +/** Renders every failure as the protocol's {@code {errorCode, message}} body. */ +@RestControllerAdvice +public class GlobalExceptionHandler { + + private static final Logger log = LoggerFactory.getLogger(GlobalExceptionHandler.class); + + @ExceptionHandler(ApiException.class) + public ResponseEntity handleApi(ApiException e) { + return body(e.getStatus(), e.getErrorCode(), e.getMessage()); + } + + @ExceptionHandler(IllegalArgumentException.class) + public ResponseEntity handleIllegalArgument(IllegalArgumentException e) { + return body(HttpStatus.BAD_REQUEST, ErrorCodes.INVALID_PARAMETER_VALUE, e.getMessage()); + } + + @ExceptionHandler({ + MethodArgumentNotValidException.class, + HandlerMethodValidationException.class, + MethodArgumentTypeMismatchException.class + }) + public ResponseEntity handleValidation(Exception e) { + return body(HttpStatus.BAD_REQUEST, ErrorCodes.INVALID_PARAMETER_VALUE, describeValidation(e)); + } + + @ExceptionHandler(HttpMessageNotReadableException.class) + public ResponseEntity handleUnreadable(HttpMessageNotReadableException e) { + return body(HttpStatus.BAD_REQUEST, ErrorCodes.MALFORMED_REQUEST, "request body is malformed"); + } + + @ExceptionHandler(DataIntegrityViolationException.class) + public ResponseEntity handleConflict(DataIntegrityViolationException e) { + log.debug("Rejected request that violated a uniqueness constraint", e); + return body( + HttpStatus.CONFLICT, + ErrorCodes.RESOURCE_ALREADY_EXISTS, + "the object already exists or conflicts with an existing object"); + } + + @ExceptionHandler(NoResourceFoundException.class) + public ResponseEntity handleNoResource(NoResourceFoundException e) { + return body( + HttpStatus.NOT_FOUND, ErrorCodes.RESOURCE_DOES_NOT_EXIST, "the endpoint does not exist"); + } + + @ExceptionHandler(Exception.class) + public ResponseEntity handleUnexpected(Exception e) { + log.error("Unhandled server error", e); + return body( + HttpStatus.INTERNAL_SERVER_ERROR, ErrorCodes.INTERNAL_ERROR, "internal server error"); + } + + private static String describeValidation(Exception e) { + if (e instanceof MethodArgumentNotValidException invalid) { + return invalid.getBindingResult().getFieldErrors().stream() + .findFirst() + .map(error -> error.getField() + " " + error.getDefaultMessage()) + .orElse("request validation failed"); + } + return "request validation failed"; + } + + private static ResponseEntity body( + HttpStatus status, String errorCode, String message) { + return ResponseEntity.status(status).body(new ErrorResponse(errorCode, message)); + } +} diff --git a/server/src/main/java/io/opensharing/http/ListResponse.java b/server/src/main/java/io/opensharing/http/ListResponse.java new file mode 100644 index 000000000..0fdd9cd41 --- /dev/null +++ b/server/src/main/java/io/opensharing/http/ListResponse.java @@ -0,0 +1,13 @@ +package io.opensharing.http; + +import com.fasterxml.jackson.annotation.JsonInclude; +import java.util.List; + +/** Paginated list envelope shared by every {@code list} endpoint. */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record ListResponse(List items, String nextPageToken) { + + public static ListResponse of(List items, String nextPageToken) { + return new ListResponse<>(items, nextPageToken); + } +} diff --git a/server/src/main/java/io/opensharing/http/OffsetPage.java b/server/src/main/java/io/opensharing/http/OffsetPage.java new file mode 100644 index 000000000..c616e60c4 --- /dev/null +++ b/server/src/main/java/io/opensharing/http/OffsetPage.java @@ -0,0 +1,37 @@ +package io.opensharing.http; + +import java.util.List; +import org.springframework.data.domain.Pageable; +import org.springframework.data.domain.PageImpl; + +/** + * A page cut from a list already in memory, addressed by the absolute offset {@link OffsetPageable} + * carries. + * + *

{@link PageImpl} decides whether anything remains by page number, which is only right when every + * offset is a multiple of the page size. A client may change {@code maxResults} between requests, so + * offsets here are arbitrary and the question is answered by counting instead — otherwise a client + * that reduced its page size would be handed a token to a page that does not exist. + */ +public final class OffsetPage extends PageImpl { + + private final long offset; + private final long total; + + public static OffsetPage of(List all, Pageable pageable) { + int from = (int) Math.min(pageable.getOffset(), all.size()); + int to = (int) Math.min((long) from + pageable.getPageSize(), all.size()); + return new OffsetPage<>(all.subList(from, to), pageable, all.size()); + } + + private OffsetPage(List content, Pageable pageable, long total) { + super(content, pageable, total); + this.offset = pageable.getOffset(); + this.total = total; + } + + @Override + public boolean hasNext() { + return offset + getNumberOfElements() < total; + } +} diff --git a/server/src/main/java/io/opensharing/http/OffsetPageable.java b/server/src/main/java/io/opensharing/http/OffsetPageable.java new file mode 100644 index 000000000..b92b0f1ca --- /dev/null +++ b/server/src/main/java/io/opensharing/http/OffsetPageable.java @@ -0,0 +1,70 @@ +package io.opensharing.http; + +import org.springframework.data.domain.Pageable; +import org.springframework.data.domain.Sort; + +/** + * A {@link Pageable} addressed by absolute offset. Protocol page tokens carry an offset rather than + * a page number, so a client is free to change {@code maxResults} between requests. + */ +public final class OffsetPageable implements Pageable { + + private final int offset; + private final int limit; + + public OffsetPageable(int offset, int limit) { + if (offset < 0) { + throw new IllegalArgumentException("offset must not be negative"); + } + if (limit < 1) { + throw new IllegalArgumentException("limit must be positive"); + } + this.offset = offset; + this.limit = limit; + } + + @Override + public int getPageNumber() { + return offset / limit; + } + + @Override + public int getPageSize() { + return limit; + } + + @Override + public long getOffset() { + return offset; + } + + @Override + public Sort getSort() { + return Sort.unsorted(); + } + + @Override + public Pageable next() { + return new OffsetPageable(offset + limit, limit); + } + + @Override + public Pageable previousOrFirst() { + return hasPrevious() ? new OffsetPageable(Math.max(0, offset - limit), limit) : first(); + } + + @Override + public Pageable first() { + return new OffsetPageable(0, limit); + } + + @Override + public Pageable withPage(int pageNumber) { + return new OffsetPageable(pageNumber * limit, limit); + } + + @Override + public boolean hasPrevious() { + return offset > 0; + } +} diff --git a/server/src/main/java/io/opensharing/http/PageTokens.java b/server/src/main/java/io/opensharing/http/PageTokens.java new file mode 100644 index 000000000..226a109aa --- /dev/null +++ b/server/src/main/java/io/opensharing/http/PageTokens.java @@ -0,0 +1,52 @@ +package io.opensharing.http; + +import java.nio.charset.StandardCharsets; +import java.util.Base64; +import org.springframework.data.domain.Page; + +/** + * Opaque page tokens. The encoding is an implementation detail clients must not depend on, so the + * offset is wrapped in a versioned, base64url-encoded envelope. + */ +public final class PageTokens { + + private static final String PREFIX = "os1:"; + + private PageTokens() {} + + /** Returns the offset a client asked to resume from, or 0 when no token was supplied. */ + public static int offsetOf(String pageToken) { + if (pageToken == null || pageToken.isBlank()) { + return 0; + } + try { + String decoded = + new String( + Base64.getUrlDecoder().decode(pageToken.trim()), StandardCharsets.UTF_8); + if (!decoded.startsWith(PREFIX)) { + throw new IllegalArgumentException("unexpected token envelope"); + } + int offset = Integer.parseInt(decoded.substring(PREFIX.length())); + if (offset < 0) { + throw new IllegalArgumentException("negative offset"); + } + return offset; + } catch (IllegalArgumentException e) { + throw ApiException.invalidParameter("pageToken is not a valid page token"); + } + } + + /** Returns the token for the page after {@code page}, or null when the results are exhausted. */ + public static String nextToken(Page page, int offset) { + if (!page.hasNext()) { + return null; + } + return encode(offset + page.getNumberOfElements()); + } + + public static String encode(int offset) { + return Base64.getUrlEncoder() + .withoutPadding() + .encodeToString((PREFIX + offset).getBytes(StandardCharsets.UTF_8)); + } +} diff --git a/server/src/main/java/io/opensharing/http/ProtocolMediaType.java b/server/src/main/java/io/opensharing/http/ProtocolMediaType.java new file mode 100644 index 000000000..358f76321 --- /dev/null +++ b/server/src/main/java/io/opensharing/http/ProtocolMediaType.java @@ -0,0 +1,9 @@ +package io.opensharing.http; + +/** Content type the spec requires on successful protocol responses. */ +public final class ProtocolMediaType { + + public static final String JSON_UTF8 = "application/json;charset=utf-8"; + + private ProtocolMediaType() {} +} diff --git a/server/src/main/java/io/opensharing/protocol/AwsCredentials.java b/server/src/main/java/io/opensharing/protocol/AwsCredentials.java new file mode 100644 index 000000000..b3fe84872 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/AwsCredentials.java @@ -0,0 +1,3 @@ +package io.opensharing.protocol; + +public record AwsCredentials(String accessKeyId, String secretAccessKey, String sessionToken) {} diff --git a/server/src/main/java/io/opensharing/protocol/AzureUserDelegationSas.java b/server/src/main/java/io/opensharing/protocol/AzureUserDelegationSas.java new file mode 100644 index 000000000..b19a7808b --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/AzureUserDelegationSas.java @@ -0,0 +1,3 @@ +package io.opensharing.protocol; + +public record AzureUserDelegationSas(String sasToken) {} diff --git a/server/src/main/java/io/opensharing/protocol/ChangeFileAction.java b/server/src/main/java/io/opensharing/protocol/ChangeFileAction.java new file mode 100644 index 000000000..995f99e80 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/ChangeFileAction.java @@ -0,0 +1,23 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; +import java.util.Map; + +/** + * One file of a change data feed, sent as an {@code add}, {@code cdf} or {@code remove} line + * depending on what it records. The three shapes are identical but for statistics, which only an + * added file carries. + * + * @param version the table version this change belongs to, which a streaming reader tracks + * @param timestamp the commit's timestamp, in epoch milliseconds + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record ChangeFileAction( + String url, + String id, + Map partitionValues, + long size, + long timestamp, + long version, + String stats, + Long expirationTimestamp) {} diff --git a/server/src/main/java/io/opensharing/protocol/EndStreamAction.java b/server/src/main/java/io/opensharing/protocol/EndStreamAction.java new file mode 100644 index 000000000..790051155 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/EndStreamAction.java @@ -0,0 +1,14 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * Closes a Delta read response, so a client can tell a complete stream from a truncated one. Sent + * only when the client asks for it through the {@code delta-sharing-capabilities} header. + * + * @param minUrlExpirationTimestamp the earliest expiry among the urls in this response, which tells + * a client when it must ask again + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record EndStreamAction( + String refreshToken, String nextPageToken, Long minUrlExpirationTimestamp) {} diff --git a/server/src/main/java/io/opensharing/protocol/FileAction.java b/server/src/main/java/io/opensharing/protocol/FileAction.java new file mode 100644 index 000000000..91871d27a --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/FileAction.java @@ -0,0 +1,22 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; +import java.util.Map; + +/** + * One data file, with a url the recipient reads directly. + * + * @param id stable for a given file across responses, so a client can cache the bytes against it + * @param stats the log's statistics JSON, passed through, which a client may use or ignore + * @param expirationTimestamp when the url stops working, in epoch milliseconds + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record FileAction( + String url, + String id, + Map partitionValues, + long size, + String stats, + Long version, + Long timestamp, + Long expirationTimestamp) {} diff --git a/server/src/main/java/io/opensharing/protocol/GcpOauthToken.java b/server/src/main/java/io/opensharing/protocol/GcpOauthToken.java new file mode 100644 index 000000000..12bc7545d --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/GcpOauthToken.java @@ -0,0 +1,3 @@ +package io.opensharing.protocol; + +public record GcpOauthToken(String oauthToken) {} diff --git a/server/src/main/java/io/opensharing/protocol/GetShareResponse.java b/server/src/main/java/io/opensharing/protocol/GetShareResponse.java new file mode 100644 index 000000000..c359f38df --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/GetShareResponse.java @@ -0,0 +1,4 @@ +package io.opensharing.protocol; + +/** {@code GET /shares/{share}} wraps the share in a single-field object. */ +public record GetShareResponse(Share share) {} diff --git a/server/src/main/java/io/opensharing/protocol/IcebergConfig.java b/server/src/main/java/io/opensharing/protocol/IcebergConfig.java new file mode 100644 index 000000000..3409bcde6 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/IcebergConfig.java @@ -0,0 +1,14 @@ +package io.opensharing.protocol; + +import java.util.List; +import java.util.Map; + +/** + * Response of the Iceberg REST catalog {@code GET /v1/config} handshake. + * + * @param overrides carries {@code prefix}, the path prefix the client must use for every later call, + * which is how a share is selected + * @param endpoints the catalog operations this server implements + */ +public record IcebergConfig( + Map defaults, Map overrides, List endpoints) {} diff --git a/server/src/main/java/io/opensharing/protocol/MetadataAction.java b/server/src/main/java/io/opensharing/protocol/MetadataAction.java new file mode 100644 index 000000000..fe3408c7e --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/MetadataAction.java @@ -0,0 +1,32 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; +import java.util.List; +import java.util.Map; + +/** + * A table's metadata as a Delta read response reports it. + * + * @param schemaString the schema as a JSON string, which the client deserializes itself + * @param location the table root, which must be present for a table offering {@code dir} access + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record MetadataAction( + String id, + String name, + String description, + String location, + List auxiliaryLocations, + List accessModes, + Format format, + String schemaString, + List partitionColumns, + Map configuration, + Long version, + Long size, + Long numFiles) { + + /** The encoding of the table's data files. */ + @JsonInclude(JsonInclude.Include.NON_NULL) + public record Format(String provider, Map options) {} +} diff --git a/server/src/main/java/io/opensharing/protocol/ProfileFile.java b/server/src/main/java/io/opensharing/protocol/ProfileFile.java new file mode 100644 index 000000000..fc5f33414 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/ProfileFile.java @@ -0,0 +1,19 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * The {@code config.share} profile file a recipient downloads from an activation URL. + * + * @param expirationTime ISO-8601 instant, or null when the token never expires + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record ProfileFile( + int shareCredentialsVersion, + String endpoint, + String icebergEndpoint, + String bearerToken, + String expirationTime) { + + public static final int CURRENT_VERSION = 1; +} diff --git a/server/src/main/java/io/opensharing/protocol/ProtocolAction.java b/server/src/main/java/io/opensharing/protocol/ProtocolAction.java new file mode 100644 index 000000000..507628639 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/ProtocolAction.java @@ -0,0 +1,7 @@ +package io.opensharing.protocol; + +/** + * The reader version a client needs to interpret the response, so a client too old for a table is + * told rather than left to misread it. + */ +public record ProtocolAction(int minReaderVersion) {} diff --git a/server/src/main/java/io/opensharing/protocol/QueryTableRequest.java b/server/src/main/java/io/opensharing/protocol/QueryTableRequest.java new file mode 100644 index 000000000..9d6b1ccee --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/QueryTableRequest.java @@ -0,0 +1,31 @@ +package io.opensharing.protocol; + +import java.util.List; + +/** + * The body of a table query. Every field is optional, and an empty object asks for the whole latest + * snapshot. + * + *

The hints are what their name says: a server may narrow the files it returns by them, and a + * client must apply its own filter to the response regardless. This server does not narrow, so it + * accepts them and returns every file of the version asked for. + * + * @param version a version to read instead of the latest + * @param timestamp the state at a moment, as an ISO-8601 instant, exclusive with {@code version} + * @param startingVersion asks for data change files since that version rather than a snapshot + */ +public record QueryTableRequest( + List predicateHints, + String jsonPredicateHints, + Integer limitHint, + Long version, + String timestamp, + Long startingVersion, + Long endingVersion, + Boolean includeHistoricalProtocol, + String idempotencyKey) { + + public static QueryTableRequest snapshot() { + return new QueryTableRequest(null, null, null, null, null, null, null, null, null); + } +} diff --git a/server/src/main/java/io/opensharing/protocol/R2Credentials.java b/server/src/main/java/io/opensharing/protocol/R2Credentials.java new file mode 100644 index 000000000..b34a4b6a5 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/R2Credentials.java @@ -0,0 +1,3 @@ +package io.opensharing.protocol; + +public record R2Credentials(String accessKeyId, String secretAccessKey, String sessionToken) {} diff --git a/server/src/main/java/io/opensharing/protocol/Schema.java b/server/src/main/java/io/opensharing/protocol/Schema.java new file mode 100644 index 000000000..dc8c5b0f4 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/Schema.java @@ -0,0 +1,4 @@ +package io.opensharing.protocol; + +/** A schema inside a share. Schemas are derived from the assets shared under them. */ +public record Schema(String name, String share) {} diff --git a/server/src/main/java/io/opensharing/protocol/Share.java b/server/src/main/java/io/opensharing/protocol/Share.java new file mode 100644 index 000000000..ddc9aff37 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/Share.java @@ -0,0 +1,9 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; +import java.util.Map; + +/** A share as returned by {@code GET /shares} and {@code GET /shares/{share}}. */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record Share( + String name, String id, String displayName, String comment, Map properties) {} diff --git a/server/src/main/java/io/opensharing/protocol/Table.java b/server/src/main/java/io/opensharing/protocol/Table.java new file mode 100644 index 000000000..db20226be --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/Table.java @@ -0,0 +1,22 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; +import java.util.List; + +/** + * A shared table, as {@code spec/protocols/TABLES.md} and the Delta Sharing protocol define it. + * + *

{@code location} is where the table's log and data live, and must be present whenever + * {@code accessModes} includes {@code dir}, since that is all a directory-access client is given to + * work from. + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record Table( + String name, + String schema, + String share, + String shareId, + String id, + String location, + List auxiliaryLocations, + List accessModes) {} diff --git a/server/src/main/java/io/opensharing/protocol/TableAction.java b/server/src/main/java/io/opensharing/protocol/TableAction.java new file mode 100644 index 000000000..62647efbe --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/TableAction.java @@ -0,0 +1,46 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * One line of a Delta read response. The protocol sends newline-delimited JSON where each line is + * this wrapper carrying exactly one action, so the factories are the only way to build one. + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record TableAction( + ProtocolAction protocol, + MetadataAction metaData, + FileAction file, + ChangeFileAction add, + ChangeFileAction cdf, + ChangeFileAction remove, + EndStreamAction endStreamAction) { + + public static TableAction of(ProtocolAction protocol) { + return new TableAction(protocol, null, null, null, null, null, null); + } + + public static TableAction of(MetadataAction metadata) { + return new TableAction(null, metadata, null, null, null, null, null); + } + + public static TableAction of(FileAction file) { + return new TableAction(null, null, file, null, null, null, null); + } + + public static TableAction added(ChangeFileAction change) { + return new TableAction(null, null, null, change, null, null, null); + } + + public static TableAction changed(ChangeFileAction change) { + return new TableAction(null, null, null, null, change, null, null); + } + + public static TableAction removed(ChangeFileAction change) { + return new TableAction(null, null, null, null, null, change, null); + } + + public static TableAction of(EndStreamAction endStream) { + return new TableAction(null, null, null, null, null, null, endStream); + } +} diff --git a/server/src/main/java/io/opensharing/protocol/TemporaryCredentials.java b/server/src/main/java/io/opensharing/protocol/TemporaryCredentials.java new file mode 100644 index 000000000..816352730 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/TemporaryCredentials.java @@ -0,0 +1,32 @@ +package io.opensharing.protocol; + +import com.fasterxml.jackson.annotation.JsonInclude; + +/** + * Response of the {@code temporary-table-credentials} endpoint. Exactly one of the cloud-specific + * fields is populated; {@code expirationTime} is epoch milliseconds. + */ +@JsonInclude(JsonInclude.Include.NON_NULL) +public record TemporaryCredentials( + AwsCredentials awsTempCredentials, + AzureUserDelegationSas azureUserDelegationSas, + GcpOauthToken gcpOauthToken, + R2Credentials r2Credentials, + long expirationTime) { + + public static TemporaryCredentials aws(AwsCredentials credentials, long expirationTime) { + return new TemporaryCredentials(credentials, null, null, null, expirationTime); + } + + public static TemporaryCredentials azure(AzureUserDelegationSas sas, long expirationTime) { + return new TemporaryCredentials(null, sas, null, null, expirationTime); + } + + public static TemporaryCredentials gcp(GcpOauthToken token, long expirationTime) { + return new TemporaryCredentials(null, null, token, null, expirationTime); + } + + public static TemporaryCredentials r2(R2Credentials credentials, long expirationTime) { + return new TemporaryCredentials(null, null, null, credentials, expirationTime); + } +} diff --git a/server/src/main/java/io/opensharing/protocol/TemporaryCredentialsRequest.java b/server/src/main/java/io/opensharing/protocol/TemporaryCredentialsRequest.java new file mode 100644 index 000000000..d8b6d6188 --- /dev/null +++ b/server/src/main/java/io/opensharing/protocol/TemporaryCredentialsRequest.java @@ -0,0 +1,9 @@ +package io.opensharing.protocol; + +/** + * Optional body of a {@code temporary-table-credentials} request. + * + * @param location for tables with auxiliary locations, which one to scope credentials to; the + * table's root location is used when omitted + */ +public record TemporaryCredentialsRequest(String location) {} diff --git a/server/src/main/resources/application.yml b/server/src/main/resources/application.yml new file mode 100644 index 000000000..061840e5c --- /dev/null +++ b/server/src/main/resources/application.yml @@ -0,0 +1,31 @@ +# Defaults for a local run. Any key here can be overridden per environment without editing the file: +# pass --the.key.path=value as an argument, or set the upper-case underscored form of the path. +spring: + application: + name: opensharing-server + datasource: + # The driver is derived from the URL, so pointing this at Postgres or MySQL is the only change + # needed to move the metadata store there. + url: jdbc:h2:file:./data/opensharing;AUTO_SERVER=TRUE + username: sa + password: "" + jpa: + hibernate: + ddl-auto: update + open-in-view: false + jackson: + default-property-inclusion: non_null + mapper: + accept-case-insensitive-enums: true + serialization: + write-dates-as-timestamps: false + +server: + port: 8080 + error: + whitelabel: + enabled: false + +logging: + level: + io.opensharing: INFO diff --git a/server/src/test/java/io/opensharing/ObjectNamesTest.java b/server/src/test/java/io/opensharing/ObjectNamesTest.java new file mode 100644 index 000000000..4e06b32dc --- /dev/null +++ b/server/src/test/java/io/opensharing/ObjectNamesTest.java @@ -0,0 +1,44 @@ +package io.opensharing; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertThrows; + +import org.junit.jupiter.api.Test; + +class ObjectNamesTest { + + @Test + void acceptsOrdinaryNames() { + assertEquals("vaccine_share", ObjectNames.validateShareName("vaccine_share")); + assertEquals("acme-data", ObjectNames.validateSchemaName("acme-data")); + assertEquals("orders", ObjectNames.validateAssetName("orders")); + } + + @Test + void rejectsRestrictedCharacters() { + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateShareName("my share")); + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateShareName("a/b")); + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateShareName("a\u0001b")); + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateShareName("a\u007fb")); + } + + @Test + void rejectsPeriodOnlyForSchemasAndAssets() { + assertEquals("share.with.dots", ObjectNames.validateShareName("share.with.dots")); + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateSchemaName("a.b")); + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateAssetName("a.b")); + } + + @Test + void rejectsEmptyAndOverlongNames() { + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateShareName("")); + assertThrows(IllegalArgumentException.class, () -> ObjectNames.validateShareName(null)); + assertThrows( + IllegalArgumentException.class, () -> ObjectNames.validateShareName("x".repeat(256))); + } + + @Test + void normalizesForCaseInsensitiveComparison() { + assertEquals("vaccine_share", ObjectNames.normalize("Vaccine_Share")); + } +} diff --git a/server/src/test/java/io/opensharing/OpenSharingServerTest.java b/server/src/test/java/io/opensharing/OpenSharingServerTest.java new file mode 100644 index 000000000..5bbbe147a --- /dev/null +++ b/server/src/test/java/io/opensharing/OpenSharingServerTest.java @@ -0,0 +1,11 @@ +package io.opensharing; + +import org.junit.jupiter.api.Test; +import org.springframework.boot.test.context.SpringBootTest; + +@SpringBootTest +class OpenSharingServerTest { + + @Test + void contextLoads() {} +}