diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/DeltaSharingCapabilities.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/DeltaSharingCapabilities.java index 0e15dde2b..873818143 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/DeltaSharingCapabilities.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/DeltaSharingCapabilities.java @@ -2,9 +2,11 @@ import io.delta.kernel.internal.actions.Protocol; import io.opensharing.http.ApiException; +import java.util.ArrayList; import java.util.EnumSet; import java.util.LinkedHashMap; import java.util.LinkedHashSet; +import java.util.List; import java.util.Locale; import java.util.Map; import java.util.Set; @@ -50,40 +52,102 @@ public static boolean includeEndStreamAction(String header) { return "true".equals(parse(header).get("includeendstreamaction")); } + /** + * The Delta table properties that stand for reader features, in the order they are checked, each + * with the reader feature that covers it and the value that turns the feature off. + */ + private static final List FEATURE_PROPERTIES = + List.of( + new PropertyWithOffValue("delta.columnMapping.mode", "columnmapping", "none"), + new PropertyWithOffValue("delta.enableDeletionVectors", "deletionvectors", "false")); + + private record PropertyWithOffValue(String property, String feature, String offValue) {} + + /** What to do about table features the client did not advertise. */ + private static final String ADVERTISE_OR_DISABLE = + "Query with responseFormat=delta and advertise the features in delta-sharing-capabilities," + + " or ask your data provider to disable them."; + + /** Deletion vectors stay in a protocol after they are turned off; their property decides. */ + private static final String DELETION_VECTORS = "deletionvectors"; + + /** What a client declared in {@code delta-sharing-capabilities}, parsed once per request. */ + public record Declared(Set formats, Set readerFeatures) {} + + public static Declared declared(String header) { + Map capabilities = parse(header); + String value = capabilities.get("readerfeatures"); + Set readerFeatures = new LinkedHashSet<>(); + if (value != null) { + for (String token : value.split(",")) { + readerFeatures.add(token.trim()); + } + } + return new Declared(responseFormats(capabilities), readerFeatures); + } + + /** + * A table whose Delta properties enable a reader feature the client did not advertise cannot be + * served to it: a property may only be present with the value that turns its feature off, in any + * case as Delta reads it. This covers the table's version {@code version}. + */ + public static void requireSupportedProperties( + Declared declared, Map configuration, long version) { + if (configuration == null || configuration.isEmpty()) { + return; + } + List unsupported = new ArrayList<>(); + for (PropertyWithOffValue checked : FEATURE_PROPERTIES) { + String value = configuration.get(checked.property()); + if (value != null + && !declared.readerFeatures().contains(checked.feature()) + && !checked.offValue().equalsIgnoreCase(value.trim())) { + unsupported.add(checked.property()); + } + } + if (!unsupported.isEmpty()) { + throw ApiException.unsupportedFeatures(unsupported, version, ADVERTISE_OR_DISABLE); + } + } + /** * A parquet response only carries protocols with reader version 1. A client that accepts delta * must advertise every reader feature the table requires; one that accepts only parquet gets * delta for an advanced table and raises the error itself. Advertised features the server does * not know are ignored. Metadata does not enforce this so clients can inspect protocol before - * querying files. + * querying files. {@code version} is the table version {@code protocol} is of. */ public static void requireReaderFeatures( - String header, ResponseFormat format, Protocol protocol) { + Declared declared, ResponseFormat format, Protocol protocol, long version) { + Set required = protocol.getReaderFeatures(); if (format != ResponseFormat.DELTA) { if (protocol.getMinReaderVersion() > 1) { - throw ApiException.invalidParameter( - "The table requires reader features that are only available in delta format"); + throw ApiException.unsupportedFeatures( + required == null || required.isEmpty() + ? List.of("reader version " + protocol.getMinReaderVersion()) + : lowerCase(required), + version, + ADVERTISE_OR_DISABLE); } return; } - if (!responseFormats(parse(header)).contains(ResponseFormat.DELTA)) { - return; - } - Set required = protocol.getReaderFeatures(); - if (required == null || required.isEmpty()) { + if (!declared.formats().contains(ResponseFormat.DELTA) || required == null) { return; } - Set advertised = advertisedReaderFeatures(header); - for (String feature : required) { - if (!advertised.contains(feature.toLowerCase(Locale.ROOT))) { - throw ApiException.invalidParameter( - "The table requires reader feature '" - + feature - + "' which was not specified in delta-sharing-capabilities"); - } + List unadvertised = + lowerCase(required).stream() + .filter(feature -> !feature.equals(DELETION_VECTORS)) + .filter(feature -> !declared.readerFeatures().contains(feature)) + .toList(); + if (!unadvertised.isEmpty()) { + throw ApiException.unsupportedFeatures(unadvertised, version, ADVERTISE_OR_DISABLE); } } + private static List lowerCase(Set features) { + return features.stream().map(feature -> feature.toLowerCase(Locale.ROOT)).toList(); + } + /** * The capabilities this server knows. Clients advertise ones it does not, such as asyncquery, * and may send parts without a value; both are ignored. @@ -133,16 +197,4 @@ static Set responseFormats(Map capabilities) { } return requested; } - - private static Set advertisedReaderFeatures(String header) { - String value = parse(header).get("readerfeatures"); - if (value == null) { - return Set.of(); - } - Set advertised = new LinkedHashSet<>(); - for (String token : value.split(",")) { - advertised.add(token.trim()); - } - return advertised; - } } diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/ProtocolTables.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/ProtocolTables.java index 99a511b42..6c0ea45d0 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/ProtocolTables.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/ProtocolTables.java @@ -7,6 +7,7 @@ import io.opensharing.asset.table.delta.DeltaKernel; import io.opensharing.asset.table.delta.DeltaTableMetadataReader; import io.opensharing.asset.table.delta.DeltaTableQueryReader; +import io.opensharing.asset.table.delta.SourceTableException; import io.opensharing.auth.AuthContext; import io.opensharing.auth.UserContext; import io.opensharing.catalog.AssetLocation; @@ -33,6 +34,7 @@ import java.util.Locale; import java.util.Optional; import java.util.function.Function; +import java.util.function.Supplier; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -124,8 +126,12 @@ public long version( String startingTimestamp) { ShareEntity share = protocolShares.requireGranted(recipient, shareName); Instant timestamp = parseTimestamp("startingTimestamp", startingTimestamp); - return kernel.getVersion( - findTable(share, schemaAlias, tableAlias).catalogTable(), timestamp, owner(share)); + ResolvedAsset table = findTable(share, schemaAlias, tableAlias).catalogTable(); + return readingTable( + share, + schemaAlias, + tableAlias, + () -> kernel.getVersion(table, timestamp, owner(share))); } /** @@ -142,9 +148,15 @@ public DeltaTableMetadataReader.Result metadata( String timestamp, String capabilities) { ShareEntity share = protocolShares.requireGranted(recipient, shareName); + TableRequestChecks.requireAtMostOne("version,timestamp", version, timestamp); + TableRequestChecks.requireNotNegative("version", version); Instant asOf = parseTimestamp("timestamp", timestamp); ResolvedAsset table = findTable(share, schemaAlias, tableAlias).catalogTable(); - return metadataReader.read(table, version, asOf, owner(share), capabilities); + return readingTable( + share, + schemaAlias, + tableAlias, + () -> metadataReader.read(table, version, asOf, owner(share), capabilities)); } /** @@ -202,12 +214,17 @@ public void query( DeltaTableQueryReader.ResponseOptions options, DeltaTableQueryReader.ResponseSink sink) { ShareEntity share = protocolShares.requireGranted(recipient, shareName); + QueryTableRequest body = request == null ? QueryTableRequest.EMPTY : request; + requireValid(body); ResolvedAsset catalogTable = requireUrlAccess( findTable(share, schemaAlias, tableAlias).catalogTable(), schemaAlias, tableAlias); - QueryTableRequest body = request == null ? QueryTableRequest.EMPTY : request; if (body.startingVersion() != null || body.endingVersion() != null) { - queryChanges(body, catalogTable, share, options, sink); + readingTable( + share, + schemaAlias, + tableAlias, + () -> queryChanges(body, catalogTable, share, options, sink)); return; } boolean historical = body.version() != null || body.timestamp() != null; @@ -223,17 +240,23 @@ public void query( if (body.predicateHints() != null && !body.predicateHints().isEmpty()) { log.debug("Ignoring deprecated predicateHints {}", body.predicateHints()); } - queryReader.read( - catalogTable, - owner(share), - options, - sink, - body.version(), - parseTimestamp("timestamp", body.timestamp()), - body.refreshToken(), - includeRefreshToken, - body.jsonPredicateHints(), - limitHint(body)); + Instant timestamp = parseTimestamp("timestamp", body.timestamp()); + readingTable( + share, + schemaAlias, + tableAlias, + () -> + queryReader.read( + catalogTable, + owner(share), + options, + sink, + body.version(), + timestamp, + body.refreshToken(), + includeRefreshToken, + body.jsonPredicateHints(), + limitHint(body))); } /** @@ -251,20 +274,80 @@ public void changes( DeltaTableQueryReader.ResponseOptions options, DeltaTableQueryReader.ResponseSink sink) { ShareEntity share = protocolShares.requireGranted(recipient, shareName); + requireValid(request); ResolvedAsset catalogTable = requireUrlAccess( findTable(share, schemaAlias, tableAlias).catalogTable(), schemaAlias, tableAlias); - queryReader.readChangeDataFeed( - catalogTable, - owner(share), - options, - sink, - request.startingVersion(), - parseTimestamp("startingTimestamp", request.startingTimestamp()), - request.endingVersion(), - parseTimestamp("endingTimestamp", request.endingTimestamp()), - Boolean.TRUE.equals(request.includeHistoricalMetadata()), - Boolean.TRUE.equals(request.includeHistoricalProtocol())); + Instant startingTimestamp = parseTimestamp("startingTimestamp", request.startingTimestamp()); + Instant endingTimestamp = parseTimestamp("endingTimestamp", request.endingTimestamp()); + readingTable( + share, + schemaAlias, + tableAlias, + () -> + queryReader.readChangeDataFeed( + catalogTable, + owner(share), + options, + sink, + request.startingVersion(), + startingTimestamp, + request.endingVersion(), + endingTimestamp, + Boolean.TRUE.equals(request.includeHistoricalMetadata()), + Boolean.TRUE.equals(request.includeHistoricalProtocol()))); + } + + /** The version parameters of a snapshot or data change query, in the order they are checked.*/ + private static void requireValid(QueryTableRequest body) { + TableRequestChecks.requireNotNegative("table version", body.version()); + TableRequestChecks.requireNotNegative("startingVersion", body.startingVersion()); + TableRequestChecks.requireNotNegative("endingVersion", body.endingVersion()); + TableRequestChecks.requireAtMostOne( + "version,timestamp,startingVersion", + body.version(), + body.timestamp(), + body.startingVersion()); + TableRequestChecks.requireOrderedVersions(body.startingVersion(), body.endingVersion()); + } + + /** The range parameters of a Change Data Feed query, in the order they are checked. */ + private static void requireValid(TableChangesRequest request) { + TableRequestChecks.requireOneBoundary( + "starting", request.startingVersion(), request.startingTimestamp()); + TableRequestChecks.requireOneBoundary( + "ending", request.endingVersion(), request.endingTimestamp()); + TableRequestChecks.requireStart(request.startingVersion(), request.startingTimestamp()); + TableRequestChecks.requireNotNegative("startingVersion", request.startingVersion()); + TableRequestChecks.requireNotNegative("endingVersion", request.endingVersion()); + if (request.startingVersion() != null && request.endingVersion() != null) { + TableRequestChecks.requireOrderedRange(request.startingVersion(), request.endingVersion()); + } + } + + /** + * Reads the table, answering a failure of the source table itself in the table's name as the + * share gives it, since the recipient knows no other. + */ + private T readingTable( + ShareEntity share, String schemaAlias, String tableAlias, Supplier read) { + try { + return read.get(); + } catch (SourceTableException failed) { + throw failed.forRecipient(share.getName() + "." + schemaAlias + "." + tableAlias); + } + } + + private void readingTable( + ShareEntity share, String schemaAlias, String tableAlias, Runnable read) { + readingTable( + share, + schemaAlias, + tableAlias, + () -> { + read.run(); + return null; + }); } /** Returns {@code catalogTable} once it is known to support the {@code url} access mode. */ @@ -293,21 +376,10 @@ private void queryChanges( if (startingVersion == null) { throw ApiException.invalidParameter("endingVersion requires startingVersion"); } - if (body.version() != null || body.timestamp() != null) { - throw ApiException.invalidParameter( - "Only one of version, timestamp, and startingVersion can be set"); - } if (Boolean.TRUE.equals(body.includeRefreshToken()) || body.refreshToken() != null) { throw ApiException.invalidParameter( "includeRefreshToken and refreshToken cannot be used with startingVersion"); } - if (startingVersion < 0) { - throw ApiException.invalidParameter("startingVersion must be non-negative"); - } - if (endingVersion != null && endingVersion < startingVersion) { - throw ApiException.invalidParameter( - "endingVersion must be greater than or equal to startingVersion"); - } queryReader.readChanges( table, owner(share), diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/TableRequestChecks.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/TableRequestChecks.java new file mode 100644 index 000000000..4ef0248ee --- /dev/null +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/TableRequestChecks.java @@ -0,0 +1,111 @@ +package io.opensharing.asset.table; + +import io.opensharing.http.ApiException; +import java.util.Arrays; +import java.util.Objects; + +/** + * The checks and messages for a table request's version, timestamp and range parameters, which + * answer INVALID_PARAMETER_VALUE. + */ +public final class TableRequestChecks { + + private TableRequestChecks() {} + + /** {@code value} as a version, or null if absent. */ + public static Long parseVersion(String name, String value) { + if (value == null) { + return null; + } + try { + return Long.parseLong(value.trim()); + } catch (NumberFormatException invalid) { + throw ApiException.invalidParameter(name + " is not a valid number."); + } + } + + public static void requireNotNegative(String name, Long version) { + if (version != null && version < 0) { + throw ApiException.invalidParameter(name + " cannot be negative."); + } + } + + /** At most one of the parameters {@code names} lists can be set, as {@code values} say. */ + public static void requireAtMostOne(String names, Object... values) { + if (Arrays.stream(values).filter(Objects::nonNull).count() > 1) { + throw ApiException.invalidParameter("Please only provide one of: " + names); + } + } + + /** A query's starting version cannot be after its ending version. */ + public static void requireOrderedVersions(Long startingVersion, Long endingVersion) { + if (startingVersion != null && endingVersion != null && endingVersion < startingVersion) { + throw ApiException.invalidParameter( + "startingVersion(" + + startingVersion + + ") must be smaller than or equal to endingVersion(" + + endingVersion + + ")."); + } + } + + /** A Change Data Feed read needs a starting version or timestamp. */ + public static void requireStart(Object startingVersion, Object startingTimestamp) { + if (startingVersion == null && startingTimestamp == null) { + throw ApiException.invalidParameter( + "No startingVersion or startingTimestamp provided for CDF read. Set one of them on the" + + " request's cdfOptions to bound the CDC range."); + } + } + + /** A Change Data Feed range cannot end before it starts. */ + public static void requireOrderedRange(long start, long end) { + if (end < start) { + throw ApiException.invalidParameter( + "CDF range from startingVersion " + + start + + " to endingVersion " + + end + + " was invalid. End cannot be before start."); + } + } + + /** At most one of a Change Data Feed range's version and timestamp, for its {@code bound}. */ + public static void requireOneBoundary(String bound, Object version, Object timestamp) { + if (version != null && timestamp != null) { + throw ApiException.invalidParameter( + "Multiple " + + bound + + " arguments provided for CDF read. Please provide one of either " + + bound + + "Timestamp or " + + bound + + "Version."); + } + } + + /** The versions of a Change Data Feed range that the table has: not after {@code latest}. */ + public static void requireStartAtMostLatest(long start, long latest) { + if (start > latest) { + throw ApiException.invalidParameter( + "Provided Start version(" + + start + + ") for reading change data is invalid. Start version cannot be greater than the" + + " latest version of the table(" + + latest + + ")."); + } + } + + public static void requireEndAtMostLatest(long end, long latest) { + if (end > latest) { + throw ApiException.invalidParameter( + "Provided End version(" + + end + + ") for reading change data is invalid. End version cannot be greater than the" + + " latest version of the table(" + + latest + + ")."); + } + } +} diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaKernel.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaKernel.java index f76e2e5c4..8c5157f98 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaKernel.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaKernel.java @@ -1,11 +1,14 @@ package io.opensharing.asset.table.delta; -import io.delta.kernel.Snapshot; import io.delta.kernel.Table; import io.delta.kernel.defaults.engine.DefaultEngine; import io.delta.kernel.engine.Engine; +import io.delta.kernel.exceptions.InvalidTableException; +import io.delta.kernel.exceptions.KernelEngineException; import io.delta.kernel.exceptions.KernelException; import io.delta.kernel.exceptions.TableNotFoundException; +import io.delta.kernel.exceptions.UnsupportedProtocolVersionException; +import io.delta.kernel.exceptions.UnsupportedTableFeatureException; import io.delta.kernel.internal.TableImpl; import io.opensharing.asset.table.StorageLocations; import io.opensharing.auth.AuthContext; @@ -19,9 +22,18 @@ import io.opensharing.catalog.TableProperties; import io.opensharing.exception.CatalogException; import io.opensharing.http.ApiException; +import java.io.FileNotFoundException; +import java.net.URLEncoder; +import java.nio.charset.StandardCharsets; +import java.nio.file.NoSuchFileException; import java.time.Duration; import java.time.Instant; +import java.util.Comparator; +import java.util.HashSet; import java.util.List; +import java.util.Locale; +import java.util.Set; +import java.util.regex.Pattern; import org.slf4j.Logger; import org.slf4j.LoggerFactory; @@ -30,6 +42,15 @@ public class DeltaKernel { private static final Logger log = LoggerFactory.getLogger(DeltaKernel.class); static final Duration CREDENTIAL_TTL = Duration.ofMinutes(5); + private static final String CONTACT_PROVIDER = "Please contact your data provider."; + private static final String SERVER_CANNOT_READ = + "This server cannot read them. " + CONTACT_PROVIDER; + private static final int MAX_CAUSE_DEPTH = 10; + /** A location with a scheme, such as one of the table's files under another spelling. */ + private static final Pattern URI_LIKE = + Pattern.compile("[A-Za-z][A-Za-z0-9+.-]*:/{1,3}[^\\s,;'\")\\]]*[^\\s,;'\")\\]:.]"); + /** What a stripped table path is replaced with in a message the recipient gets. */ + private static final String PATH_PLACEHOLDER = "the table"; private final CatalogConnector catalog; @@ -44,53 +65,149 @@ public DeltaKernel(CatalogConnector catalog) { public long getVersion(ResolvedAsset table, Instant startingTimestamp, AuthContext auth) { try (Session session = open(table, auth)) { return versionAtOrAfter((TableImpl) session.table(), session.engine(), startingTimestamp); + } catch (KernelException | KernelEngineException failed) { + throw classifyRead(failed, table); } } + /** + * The table's latest version, or the earliest committed at or after {@code startingTimestamp}. + * A timestamp the log cannot answer is Kernel's report. + */ static long versionAtOrAfter(TableImpl table, Engine engine, Instant startingTimestamp) { - Snapshot latest = latestSnapshot(table, engine); if (startingTimestamp == null) { - return latest.getVersion(); + return table.getLatestSnapshot(engine).getVersion(); } - if (startingTimestamp.toEpochMilli() > latest.getTimestamp(engine)) { - throw ApiException.invalidParameter( - "startingTimestamp is after the latest table version timestamp"); + try { + return table.getVersionAtOrAfterTimestamp(engine, startingTimestamp.toEpochMilli()); + } catch (IllegalArgumentException failed) { + throw classify(failed, table.getPath(engine), null); } - return table.getVersionAtOrAfterTimestamp(engine, startingTimestamp.toEpochMilli()); } /** - * The table's latest snapshot. A catalog Delta table without a log is a catalog error, and a - * protocol Kernel cannot read is the recipient's. + * Classifies a Kernel failure anywhere in reading {@code table}, of which the catalog's storage + * location is all the path known. */ - static Snapshot latestSnapshot(Table table, Engine engine) { - try { - return table.getLatestSnapshot(engine); - } catch (TableNotFoundException missing) { - log.error("Delta table at '{}' has no log", table.getPath(engine)); - throw new CatalogException("the table has no Delta log"); - } catch (KernelException failed) { - if (unsupportedProtocol(failed)) { - throw unreadableTable(failed); + static RuntimeException classifyRead(RuntimeException failed, ResolvedAsset table) { + return classify( + failed, HadoopStorageConfiguration.kernelPath(table.location().storageLocation()), null); + } + + /** + * The recipient's answer to a failure reading the table, classified once. A log or file that is + * missing or cannot be accessed, or a feature this server cannot read, is the shared source + * table's own state, which its data provider controls. A log whose content Kernel rejects is + * the table's state too, and Kernel says what is wrong. Any other Kernel report, such as a + * version or timestamp the table does not have, is the request's mistake. A failure of the + * storage layer itself is not the recipient's to hear about, and stays a server error. Kernel's + * messages name the table's storage path, which stays in the log. + * + * @param version the table version the failed read was for, if the request named one + */ + static RuntimeException classify(RuntimeException failed, String tablePath, Long version) { + if (failed instanceof TableNotFoundException) { + log.warn("Delta table at '{}' has no log: {}", tablePath, failed.toString()); + return SourceTableException.unreadable(failed.toString()); + } + if (storageUnavailable(failed)) { + // A denied read can be this server's own expired or misconfigured credential, so operators + // see it as an error, while the recipient is told to contact the data provider. + log.error("Delta table at '{}' has files that cannot be read", tablePath, failed); + return SourceTableException.unreadable(failed.toString()); + } + if (failed instanceof KernelEngineException) { + // The storage layer failed for a reason of its own, which is a server error. + log.error("Delta table at '{}' failed in the storage layer", tablePath, failed); + return failed; + } + if (failed instanceof UnsupportedTableFeatureException unsupported) { + log.warn("Delta table at '{}': {}", tablePath, unsupported.getMessage()); + return ApiException.unsupportedFeatures( + unsupported.getUnsupportedFeatures().stream() + .map(feature -> feature.toLowerCase(Locale.ROOT)) + .toList(), + version, + SERVER_CANNOT_READ); + } + if (failed instanceof UnsupportedProtocolVersionException unsupported) { + log.warn("Delta table at '{}': {}", tablePath, unsupported.getMessage()); + return ApiException.unsupportedFeatures( + List.of("reader version " + unsupported.getMinReaderVersion()), + version, + SERVER_CANNOT_READ); + } + if (failed instanceof InvalidTableException) { + return kernelError(failed, tablePath, " " + CONTACT_PROVIDER); + } + return kernelError(failed, tablePath, ""); + } + + /** + * Whether the table's files could not be found or read: Kernel reports that only as the storage + * layer's own failure, which may be the filesystem library's class of the same name. + */ + private static boolean storageUnavailable(Throwable failed) { + Throwable cause = failed; + for (int depth = 0; cause != null && depth < MAX_CAUSE_DEPTH; depth++) { + if (cause instanceof FileNotFoundException + || cause instanceof NoSuchFileException + || cause.getClass().getSimpleName().equals("AccessDeniedException")) { + return true; } - throw failed; + cause = cause.getCause(); } + return false; } /** - * Whether Kernel cannot read the table's reader version or features, which it reports only by - * message. + * Kernel's report, in Kernel's own words and without the table's storage path, which stays in the + * log: every spelling of the path, and then any other location with a scheme, is removed from + * what the recipient gets. {@code suffix} is appended to the message. */ - static boolean unsupportedProtocol(KernelException failed) { - String message = failed.getMessage(); - return message != null && message.startsWith("Unsupported Delta "); + static ApiException kernelError(RuntimeException failed, String tablePath, String suffix) { + String message = + failed.getMessage() == null ? "Kernel rejected the request." : failed.getMessage(); + log.info("Kernel rejected a request for '{}': {}", tablePath, message); + for (String form : pathForms(tablePath)) { + message = message.replaceAll(Pattern.quote(form) + "(/(?=[:\\s]|$))?", PATH_PLACEHOLDER); + } + message = URI_LIKE.matcher(message).replaceAll(PATH_PLACEHOLDER); + String lead = PATH_PLACEHOLDER + ": "; + if (message.startsWith(lead)) { + message = message.substring(lead.length()); + } + return ApiException.badRequest(message + suffix); } - /** Kernel's message names the table path, so it stays in the log. */ - static ApiException unreadableTable(KernelException failed) { - log.warn("Kernel cannot read a shared table: {}", failed.getMessage()); - return ApiException.invalidParameter( - "the table requires a Delta reader version or feature this server cannot read"); + /** + * The spellings of a table path a Kernel message can carry: as given, a local path with and + * without its {@code file:} scheme, which Kernel normalizes to one slash, and with spaces escaped + * or unescaped or fully percent-encoded, since a path and its URI form differ in all of those. + * Longer spellings come + * first, so replacing one never leaves a stub of another behind. + */ + private static List pathForms(String tablePath) { + Set paths = new HashSet<>(List.of(tablePath)); + if (tablePath.startsWith("file:")) { + String local = tablePath.replaceFirst("^file:/*", "/"); + paths.addAll(List.of(local, "file:" + local, "file://" + local)); + } + Set forms = new HashSet<>(); + for (String path : paths) { + String base = path.endsWith("/") ? path.substring(0, path.length() - 1) : path; + String fullyEncoded = URLEncoder.encode(base, StandardCharsets.UTF_8); + forms.addAll( + List.of( + base, + base.replace(" ", "%20"), + base.replace("%20", " "), + base.replace(" ", "%20").replace(":", "%3A"), + fullyEncoded, + fullyEncoded.replace("+", "%20"))); + } + forms.remove(""); + return forms.stream().sorted(Comparator.comparingInt(String::length).reversed()).toList(); } /** Opens the table's root with read credentials the catalog vends to {@code auth}. */ diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaSnapshots.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaSnapshots.java index 2054b91d7..f7d53f1c1 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaSnapshots.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaSnapshots.java @@ -1,10 +1,10 @@ package io.opensharing.asset.table.delta; import io.delta.kernel.Snapshot; +import io.delta.kernel.exceptions.KernelEngineException; import io.delta.kernel.exceptions.KernelException; import io.delta.kernel.internal.SnapshotImpl; import io.delta.kernel.internal.checksum.CRCInfo; -import io.opensharing.http.ApiException; import java.time.Instant; /** Opens a Kernel snapshot for a version, timestamp, or the latest log, and reads its checksum. */ @@ -12,32 +12,22 @@ final class DeltaSnapshots { private DeltaSnapshots() {} + /** + * The snapshot at {@code version}, at {@code timestamp}, or the latest. A version or timestamp + * outside the log is Kernel's report, and is classified like every Kernel failure. + */ static Snapshot open(DeltaKernel.Session session, Long version, Instant timestamp) { - Snapshot latest = DeltaKernel.latestSnapshot(session.table(), session.engine()); - if (version != null) { - if (version > latest.getVersion()) { - throw ApiException.invalidParameter( - "version " + version + " is after the latest table version " + latest.getVersion()); - } - try { - return session.table().getSnapshotAsOfVersion(session.engine(), version); - } catch (KernelException | IllegalArgumentException unavailable) { - throw unavailable(unavailable, "version " + version + " is no longer available"); - } + if (version == null && timestamp == null) { + return session.table().getLatestSnapshot(session.engine()); } - if (timestamp != null) { - if (timestamp.toEpochMilli() > latest.getTimestamp(session.engine())) { - throw ApiException.invalidParameter( - "timestamp is after the latest table version timestamp"); - } - try { - return session.table().getSnapshotAsOfTimestamp(session.engine(), timestamp.toEpochMilli()); - } catch (KernelException | IllegalArgumentException unavailable) { - throw unavailable( - unavailable, "timestamp is before the earliest available table version timestamp"); - } + try { + return version != null + ? session.table().getSnapshotAsOfVersion(session.engine(), version) + : session.table().getSnapshotAsOfTimestamp(session.engine(), timestamp.toEpochMilli()); + } catch (KernelException | KernelEngineException | IllegalArgumentException unavailable) { + throw DeltaKernel.classify( + unavailable, session.table().getPath(session.engine()), version); } - return latest; } /** @@ -50,12 +40,4 @@ static CRCInfo crcFor(SnapshotImpl snapshot) { .filter(crc -> crc.getVersion() == snapshot.getVersion()) .orElse(null); } - - /** An earlier snapshot can need a protocol Kernel cannot read even when the latest does not. */ - private static ApiException unavailable(RuntimeException failed, String message) { - if (failed instanceof KernelException kernel && DeltaKernel.unsupportedProtocol(kernel)) { - return DeltaKernel.unreadableTable(kernel); - } - return ApiException.invalidParameter(message); - } } diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableMetadataReader.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableMetadataReader.java index 93cf6a8a2..338c349c6 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableMetadataReader.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableMetadataReader.java @@ -1,6 +1,8 @@ package io.opensharing.asset.table.delta; import io.delta.kernel.Snapshot; +import io.delta.kernel.exceptions.KernelEngineException; +import io.delta.kernel.exceptions.KernelException; import io.delta.kernel.internal.SnapshotImpl; import io.delta.kernel.internal.checksum.CRCInfo; import io.opensharing.asset.table.DeltaSharingCapabilities; @@ -8,7 +10,6 @@ import io.opensharing.asset.table.TableActions; import io.opensharing.auth.AuthContext; import io.opensharing.catalog.ResolvedAsset; -import io.opensharing.http.ApiException; import java.time.Instant; /** @@ -29,12 +30,13 @@ public Result read( Instant timestamp, AuthContext auth, String capabilities) { - if (version != null && timestamp != null) { - throw ApiException.invalidParameter("version and timestamp are mutually exclusive"); - } try (DeltaKernel.Session session = kernel.open(table, auth)) { Snapshot snapshot = DeltaSnapshots.open(session, version, timestamp); SnapshotImpl impl = (SnapshotImpl) snapshot; + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared(capabilities), + impl.getMetadata().getConfiguration(), + snapshot.getVersion()); boolean historical = version != null || timestamp != null; ResponseFormat format = DeltaSharingCapabilities.choose(capabilities, impl.getProtocol().getMinReaderVersion()); @@ -50,6 +52,8 @@ public Result read( crc == null ? null : crc.getTableSizeBytes(), crc == null ? null : crc.getNumFiles(), format)); + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); } } diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableQueryReader.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableQueryReader.java index 378e745f7..5b55c8c93 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableQueryReader.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableQueryReader.java @@ -7,6 +7,7 @@ import io.delta.kernel.data.ColumnarBatch; import io.delta.kernel.data.FilteredColumnarBatch; import io.delta.kernel.data.Row; +import io.delta.kernel.exceptions.KernelEngineException; import io.delta.kernel.exceptions.KernelException; import io.delta.kernel.expressions.Predicate; import io.delta.kernel.internal.DeltaLogActionUtils; @@ -39,6 +40,7 @@ import io.opensharing.asset.table.StorageLocations; import io.opensharing.asset.table.TableActions; import io.opensharing.asset.table.TableActions.ChangeType; +import io.opensharing.asset.table.TableRequestChecks; import io.opensharing.asset.table.signer.SignedUrl; import io.opensharing.asset.table.signer.SigningSession; import io.opensharing.asset.table.signer.UrlSigners; @@ -81,6 +83,10 @@ public class DeltaTableQueryReader { // Commit files are read directly because Kernel 4.0's getChanges requires commitInfo fields that // older Delta writers omit; only the commitInfo fields used here are read. + private static final StructType PROTOCOL_AND_METADATA_SCHEMA = + new StructType() + .add(DeltaAction.PROTOCOL.colName, DeltaAction.PROTOCOL.schema) + .add(DeltaAction.METADATA.colName, DeltaAction.METADATA.schema); private static final StructType CHANGE_SCHEMA = new StructType() .add(DeltaAction.PROTOCOL.colName, DeltaAction.PROTOCOL.schema) @@ -127,9 +133,6 @@ public void read( boolean includeRefreshToken, String jsonPredicateHints, Long limitHint) { - if (version != null && timestamp != null) { - throw ApiException.invalidParameter("version and timestamp are mutually exclusive"); - } // A time-travel query reports the snapshot version in metaData and on every file. boolean historical = version != null || timestamp != null; // A refresh token pins the version it was issued for without making the query historical. @@ -141,7 +144,8 @@ public void read( ResponseWriter out = new ResponseWriter(session, table, options, sink)) { Snapshot snapshot = DeltaSnapshots.open(session, version, timestamp); SnapshotImpl impl = (SnapshotImpl) snapshot; - out.requireReaderFeatures(impl.getProtocol()); + out.requireSupportedProperties(impl.getMetadata(), snapshot.getVersion()); + out.requireReaderFeatures(impl.getProtocol(), snapshot.getVersion()); Long fileVersion = historical ? snapshot.getVersion() : null; Long fileTimestamp = historical ? snapshot.getTimestamp(session.engine()) : null; out.begin(snapshot.getVersion()); @@ -181,6 +185,8 @@ public void read( table.catalogAssetId(), snapshot.getVersion(), Instant.now().plus(URL_TTL)) : null); } + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); } } @@ -201,9 +207,9 @@ public void readChanges( boolean includeHistoricalProtocol) { try (DeltaKernel.Session session = kernel.open(table, auth, URL_TTL)) { long latest = DeltaSnapshots.open(session, null, null).getVersion(); - requireAtMostLatest("startingVersion", startingVersion, latest); + TableRequestChecks.requireStartAtMostLatest(startingVersion, latest); if (endingVersion != null) { - requireAtMostLatest("endingVersion", endingVersion, latest); + TableRequestChecks.requireEndAtMostLatest(endingVersion, latest); } changes( session, @@ -215,15 +221,17 @@ public void readChanges( includeHistoricalProtocol), options, sink); + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); } } /** - * Reads the Change Data Feed from the start through the end version or timestamp, or the latest - * version. Versions take precedence over timestamps, and an end after the latest version is - * capped, as in the OSS server. Protocol and metaData lines come from the start version with - * {@code includeHistoricalMetadata}, which also returns later metaData changes, and from the - * latest version otherwise. + * Reads the Change Data Feed from the starting version or timestamp, one of which is required, + * through the end version or timestamp, or the latest version. A start or end after the latest + * version is rejected rather than capped. Protocol and metaData lines come from the start + * version with {@code includeHistoricalMetadata}, which also returns later metaData changes, and + * from the latest version otherwise. */ public void readChangeDataFeed( ResolvedAsset table, @@ -239,32 +247,30 @@ public void readChangeDataFeed( try (DeltaKernel.Session session = kernel.open(table, auth, URL_TTL)) { SnapshotImpl latest = (SnapshotImpl) DeltaSnapshots.open(session, null, null); TableImpl delta = (TableImpl) session.table(); - long start; if (startingVersion != null) { - start = startingVersion; - } else if (startingTimestamp != null) { - start = DeltaKernel.versionAtOrAfter(delta, session.engine(), startingTimestamp); - } else { - throw ApiException.invalidParameter("startingVersion or startingTimestamp is required"); + TableRequestChecks.requireStartAtMostLatest(startingVersion, latest.getVersion()); + } + if (endingTimestamp != null) { + requireEndingTimestampAtMostLatest(endingTimestamp, latest, session); } + long start = + startingVersion != null + ? startingVersion + : DeltaKernel.versionAtOrAfter(delta, session.engine(), startingTimestamp); Long end = endingVersion != null ? endingVersion : endingTimestamp != null ? versionBeforeOrAt(delta, session, endingTimestamp) : null; - if (start < 0) { - throw ApiException.invalidParameter("startingVersion must be non-negative"); + if (end != null) { + TableRequestChecks.requireOrderedRange(start, end); + TableRequestChecks.requireEndAtMostLatest(end, latest.getVersion()); } - requireAtMostLatest("startingVersion", start, latest.getVersion()); - if (end != null && end < start) { - throw ApiException.invalidParameter( - "endingVersion " + end + " is before startingVersion " + start); - } - long resolvedEnd = end == null ? latest.getVersion() : Math.min(end, latest.getVersion()); + long resolvedEnd = end == null ? latest.getVersion() : end; SnapshotImpl first = (SnapshotImpl) DeltaSnapshots.open(session, start, null); if (!changeDataFeedEnabled(first.getMetadata())) { - throw changeDataNotRecorded(start, start, resolvedEnd); + throw SourceTableException.changeDataNotRecorded(start); } changes( session, @@ -274,6 +280,27 @@ public void readChangeDataFeed( start, resolvedEnd, includeHistoricalMetadata, includeHistoricalProtocol), options, sink); + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); + } + } + + /** + * An ending timestamp after the latest commit is the recipient's mistake, and the table's latest + * commit time says what to ask for instead. + */ + private static void requireEndingTimestampAtMostLatest( + Instant endingTimestamp, SnapshotImpl latest, DeltaKernel.Session session) { + long latestTimestamp = latest.getTimestamp(session.engine()); + if (endingTimestamp.toEpochMilli() > latestTimestamp) { + String latestInstant = Instant.ofEpochMilli(latestTimestamp).toString(); + throw ApiException.invalidParameter( + "The provided timestamp(" + + endingTimestamp + + ") is after the latest table version available to this table (" + + latestInstant + + "). Please use a timestamp less than or equal to " + + latestInstant); } } @@ -281,9 +308,8 @@ private static long versionBeforeOrAt( TableImpl table, DeltaKernel.Session session, Instant endingTimestamp) { try { return table.getVersionBeforeOrAtTimestamp(session.engine(), endingTimestamp.toEpochMilli()); - } catch (KernelException | IllegalArgumentException invalid) { - throw ApiException.invalidParameter( - "endingTimestamp is before the earliest table version timestamp"); + } catch (IllegalArgumentException invalid) { + throw DeltaKernel.classify(invalid, table.getPath(session.engine()), null); } } @@ -300,19 +326,24 @@ private void changes( ResponseOptions options, ResponseSink sink) { try (ResponseWriter out = new ResponseWriter(session, table, options, sink)) { - out.requireReaderFeatures(header.getProtocol()); + out.requireSupportedProperties(header.getMetadata(), header.getVersion()); + out.requireReaderFeatures(header.getProtocol(), header.getVersion()); Path tablePath = new Path(session.table().getPath(session.engine())); List commitFiles; try { commitFiles = DeltaLogActionUtils.getCommitFilesForVersionRange( session.engine(), tablePath, range.start(), Optional.of(range.end())); - } catch (KernelException | IllegalArgumentException missing) { - throw ApiException.invalidParameter( - "the table no longer has every commit from version " - + range.start() - + " to " - + range.end()); + } catch (IllegalArgumentException failed) { + throw DeltaKernel.classify(failed, session.table().getPath(session.engine()), null); + } + + // A failure after the response has begun can only reset the stream, so every protocol and + // metaData the range commits is checked before any line is written. + try { + checkCommits(session, out, range, commitFiles); + } catch (IOException e) { + throw new UncheckedIOException(e); } // The protocol reports the starting version as the table version of a change response. @@ -331,10 +362,10 @@ private void changes( for (FileStatus file : commitFiles) { if (range.changeDataFeed()) { Commit commit = new Commit(file); - readCommit(session, file, commit::add); + readCommit(session, file, CHANGE_SCHEMA, commit::add); write(out, range, commit); } else { - readCommit(session, file, new CommitWriter(out, range, file)::write); + readCommit(session, file, CHANGE_SCHEMA, new CommitWriter(out, range, file)::write); } } } catch (IOException e) { @@ -347,19 +378,50 @@ private void changes( } } + /** + * Checks the reader features, the Delta properties and, for a Change Data Feed, the change data + * recording of each protocol and metaData in the commits of {@code range}. + */ + private static void checkCommits( + DeltaKernel.Session session, ResponseWriter out, ChangeRange range, List files) + throws IOException { + for (FileStatus file : files) { + long version = FileNames.deltaVersion(file.getPath()); + readCommit( + session, + file, + PROTOCOL_AND_METADATA_SCHEMA, + (row, columns) -> { + if (!row.isNullAt(columns.protocol())) { + Protocol protocol = Protocol.fromRow(row.getStruct(columns.protocol())); + out.requireReaderFeatures(protocol, version); + } else if (!row.isNullAt(columns.metadata())) { + Metadata metadata = Metadata.fromRow(row.getStruct(columns.metadata())); + out.requireSupportedProperties(metadata, version); + if (range.changeDataFeed() && !changeDataFeedEnabled(metadata)) { + throw SourceTableException.changeDataNotRecorded(version); + } + } + }); + } + } + /** * Reads one commit file, which holds every action of its version, in log order. Kernel can split * a large file across several batches, each with its own schema ordinals. */ private static void readCommit( - DeltaKernel.Session session, FileStatus file, BiConsumer action) + DeltaKernel.Session session, + FileStatus file, + StructType schema, + BiConsumer action) throws IOException { try (CloseableIterator batches = session .engine() .getJsonHandler() .readJsonFiles( - Utils.singletonCloseableIterator(file), CHANGE_SCHEMA, Optional.empty())) { + Utils.singletonCloseableIterator(file), schema, Optional.empty())) { while (batches.hasNext()) { ColumnarBatch batch = batches.next(); ChangeColumns columns = ChangeColumns.of(batch.getSchema()); @@ -376,19 +438,14 @@ private static void readCommit( private static void write(ResponseWriter out, ChangeRange range, Commit commit) { long version = commit.version; boolean later = range.later(version); - if (commit.protocol != null) { - out.requireReaderFeatures(commit.protocol); - if (range.includeHistoricalProtocol() && out.format() == ResponseFormat.DELTA && later) { - out.protocol(commit.protocol, version); - } + if (commit.protocol != null + && range.includeHistoricalProtocol() + && out.format() == ResponseFormat.DELTA + && later) { + out.protocol(commit.protocol, version); } - if (commit.metadata != null) { - if (!changeDataFeedEnabled(commit.metadata)) { - throw changeDataNotRecorded(version, range.start(), range.end()); - } - if (range.includeHistoricalMetadata() && later) { - out.metadata(commit.metadata, version, null); - } + if (commit.metadata != null && range.includeHistoricalMetadata() && later) { + out.metadata(commit.metadata, version, null); } List files = commit.files; if (!commit.cdcFiles.isEmpty()) { @@ -405,17 +462,6 @@ private static boolean changeDataFeedEnabled(Metadata metadata) { return TableConfig.CHANGE_DATA_FEED_ENABLED.fromMetadata(metadata); } - private static ApiException changeDataNotRecorded(long version, long start, long end) { - return ApiException.invalidParameter( - "Error getting change data for range [" - + start - + ", " - + end - + "] as change data was not recorded for version [" - + version - + "]"); - } - // MERGE can rewrite files with dataChange but change no rows; its metrics say so, and no cdc // is written. Missing metrics do not skip. private static boolean noOpMerge(Row commitInfo) { @@ -435,13 +481,6 @@ private static boolean noOpMerge(Row commitInfo) { .allMatch(metric -> "0".equals(values.get(metric))); } - private static void requireAtMostLatest(String name, long version, long latest) { - if (version > latest) { - throw ApiException.invalidParameter( - name + " " + version + " is after the latest table version " + latest); - } - } - // Files without stats count as zero records, so limitHint never stops early on them. private static long numRecords(String stats) { if (stats == null || stats.isBlank()) { @@ -488,6 +527,7 @@ private final class ResponseWriter implements AutoCloseable { private final DeltaKernel.Session session; private final ResolvedAsset table; private final String capabilities; + private final DeltaSharingCapabilities.Declared declared; private final String fileIdHash; private final SigningSession signer; private final ResponseSink sink; @@ -503,6 +543,7 @@ private final class ResponseWriter implements AutoCloseable { this.session = session; this.table = table; this.capabilities = options.capabilities(); + this.declared = DeltaSharingCapabilities.declared(capabilities); this.fileIdHash = options.fileIdHash(); this.signer = signers.open(session.credentials()); this.sink = sink; @@ -510,13 +551,20 @@ private final class ResponseWriter implements AutoCloseable { /** * Picks the format from the first protocol, before any line is written, then checks each, as a - * later protocol can need reader features the client did not declare. + * later protocol can need reader features the client did not declare. {@code version} is the + * table version {@code protocol} is of. */ - void requireReaderFeatures(Protocol protocol) { + void requireReaderFeatures(Protocol protocol, long version) { if (format == null) { format = DeltaSharingCapabilities.choose(capabilities, protocol.getMinReaderVersion()); } - DeltaSharingCapabilities.requireReaderFeatures(capabilities, format, protocol); + DeltaSharingCapabilities.requireReaderFeatures(declared, format, protocol, version); + } + + /** Checks the Delta properties of {@code metadata}, the table's metadata at {@code version}. */ + void requireSupportedProperties(Metadata metadata, long version) { + DeltaSharingCapabilities.requireSupportedProperties( + declared, metadata.getConfiguration(), version); } /** Null until {@link #requireReaderFeatures} picks it. */ @@ -774,7 +822,6 @@ private static final class CommitWriter { void write(Row row, ChangeColumns columns) { if (!row.isNullAt(columns.protocol())) { Protocol protocol = Protocol.fromRow(row.getStruct(columns.protocol())); - out.requireReaderFeatures(protocol); if (range.includeHistoricalProtocol() && out.format() == ResponseFormat.DELTA && later) { out.protocol(protocol, version); } diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/SourceTableException.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/SourceTableException.java new file mode 100644 index 000000000..8806612e4 --- /dev/null +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/SourceTableException.java @@ -0,0 +1,52 @@ +package io.opensharing.asset.table.delta; + +import io.opensharing.http.ApiException; +import io.opensharing.http.ErrorCodes; + +/** + * The shared source table itself, which its data provider controls, failed a recipient's request. + * The recipient is told to contact the data provider and is given the table's name as the share + * names it, which only the protocol layer knows, so it turns this into an {@link ApiException} + * with {@link #forRecipient(String)}. Server-side detail, such as the table's storage path, stays + * in the log. + */ +public final class SourceTableException extends RuntimeException { + + private static final String CONTACT_PROVIDER = "Please contact your data provider."; + + private final Long changeDataMissingVersion; + + private SourceTableException(String logMessage, Long changeDataMissingVersion) { + super(logMessage); + this.changeDataMissingVersion = changeDataMissingVersion; + } + + /** The table's log or data files cannot be found or read where the catalog says they are. */ + static SourceTableException unreadable(String logMessage) { + return new SourceTableException(logMessage, null); + } + + /** The table did not record its change data for {@code version}, which a change query needs. */ + static SourceTableException changeDataNotRecorded(long version) { + return new SourceTableException( + "change data was not recorded for version " + version, version); + } + + /** The recipient's answer, naming the table {@code sharedName}, as {@code share.schema.table}. */ + public ApiException forRecipient(String sharedName) { + if (changeDataMissingVersion != null) { + return ApiException.permissionDenied( + "Unable to access change data feed for " + + sharedName + + ". CDF is not enabled on the original delta table for version " + + changeDataMissingVersion + + ". " + + CONTACT_PROVIDER); + } + return ApiException.badRequest( + "Unable to access table " + + sharedName + + ": something is wrong with the table. " + + CONTACT_PROVIDER); + } +} diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/http/ApiException.java b/server/opensharing-server-core/src/main/java/io/opensharing/http/ApiException.java index f294bab62..b88d0e4dc 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/http/ApiException.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/http/ApiException.java @@ -1,5 +1,8 @@ package io.opensharing.http; +import java.util.Collection; +import java.util.TreeSet; + /** An error with an explicit protocol error code and HTTP status. */ public class ApiException extends RuntimeException { @@ -32,6 +35,11 @@ public static ApiException conflict(String message) { return new ApiException(409, ErrorCodes.RESOURCE_CONFLICT, message); } + /** A request the server cannot serve, such as one Kernel rejected or a table it cannot read. */ + public static ApiException badRequest(String message) { + return new ApiException(400, ErrorCodes.BAD_REQUEST, message); + } + public static ApiException invalidParameter(String message) { return new ApiException(400, ErrorCodes.INVALID_PARAMETER_VALUE, message); } @@ -47,4 +55,20 @@ public static ApiException unauthenticated(String message) { public static ApiException notImplemented(String message) { return new ApiException(501, ErrorCodes.NOT_IMPLEMENTED, message); } + + /** + * The table needs Delta features or properties that cannot be served, named in a fixed order so + * the message is the same on every request. {@code version} is the table version they were found in, if known, + * and {@code remedy} tells the recipient what to do about them. + */ + public static ApiException unsupportedFeatures( + Collection features, Long version, String remedy) { + return invalidParameter( + "Table features " + + String.join(", ", new TreeSet<>(features)) + + " are found in table" + + (version == null ? "." : " version: " + version + ".") + + " " + + remedy); + } } diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/http/ErrorCodes.java b/server/opensharing-server-core/src/main/java/io/opensharing/http/ErrorCodes.java index 09614b1cd..55342f402 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/http/ErrorCodes.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/http/ErrorCodes.java @@ -3,6 +3,7 @@ /** Error codes used in {@link ErrorResponse#errorCode()}. */ public final class ErrorCodes { + public static final String BAD_REQUEST = "BAD_REQUEST"; public static final String MALFORMED_REQUEST = "MALFORMED_REQUEST"; public static final String INVALID_PARAMETER_VALUE = "INVALID_PARAMETER_VALUE"; public static final String UNAUTHENTICATED = "UNAUTHENTICATED"; diff --git a/server/opensharing-server-core/src/main/java/io/opensharing/protocol/DeltaSharingProtocolService.java b/server/opensharing-server-core/src/main/java/io/opensharing/protocol/DeltaSharingProtocolService.java index b67795fe5..8b7e28f25 100644 --- a/server/opensharing-server-core/src/main/java/io/opensharing/protocol/DeltaSharingProtocolService.java +++ b/server/opensharing-server-core/src/main/java/io/opensharing/protocol/DeltaSharingProtocolService.java @@ -23,6 +23,7 @@ import io.opensharing.asset.table.ProtocolTables; import io.opensharing.asset.table.QueryTableRequest; import io.opensharing.asset.table.TableChangesRequest; +import io.opensharing.asset.table.TableRequestChecks; import io.opensharing.asset.table.TemporaryTableCredentialsRequest; import io.opensharing.asset.table.TemporaryTableCredentialsResponse; import io.opensharing.asset.table.delta.DeltaTableMetadataReader; @@ -82,7 +83,7 @@ public HttpResponse getTableMetadata( @Param String share, @Param String schema, @Param String table, - @Param @Nullable Long version, + @Param @Nullable String version, @Param @Nullable String timestamp, @Header(DeltaSharingCapabilities.HEADER) @Nullable String capabilities) { DeltaTableMetadataReader.Result result = @@ -91,7 +92,7 @@ public HttpResponse getTableMetadata( ObjectNames.normalize(share), ObjectNames.normalize(schema), ObjectNames.normalize(table), - version, + TableRequestChecks.parseVersion("version", version), timestamp, capabilities); ResponseHeaders headers = @@ -178,9 +179,9 @@ public HttpResponse queryTableChanges( @Param String share, @Param String schema, @Param String table, - @Param @Nullable Long startingVersion, + @Param @Nullable String startingVersion, @Param @Nullable String startingTimestamp, - @Param @Nullable Long endingVersion, + @Param @Nullable String endingVersion, @Param @Nullable String endingTimestamp, @Param @Nullable Boolean includeHistoricalMetadata, @Param @Nullable Boolean includeHistoricalProtocol, @@ -188,9 +189,9 @@ public HttpResponse queryTableChanges( @Header(FileIdHash.HEADER) @Nullable String fileIdHash) { TableChangesRequest request = new TableChangesRequest( - startingVersion, + TableRequestChecks.parseVersion("startingVersion", startingVersion), startingTimestamp, - endingVersion, + TableRequestChecks.parseVersion("endingVersion", endingVersion), endingTimestamp, includeHistoricalMetadata, includeHistoricalProtocol); diff --git a/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/DeltaSharingCapabilitiesTest.java b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/DeltaSharingCapabilitiesTest.java index da3d52e2f..1f674ae1d 100644 --- a/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/DeltaSharingCapabilitiesTest.java +++ b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/DeltaSharingCapabilitiesTest.java @@ -9,6 +9,8 @@ import io.delta.kernel.internal.actions.Protocol; import io.opensharing.asset.table.DeltaSharingCapabilities.ResponseFormat; import io.opensharing.http.ApiException; +import io.opensharing.http.ErrorCodes; +import java.util.Map; import java.util.Set; import org.junit.jupiter.api.Test; @@ -63,64 +65,139 @@ private static ResponseFormat choose(String header) { return DeltaSharingCapabilities.choose(header, 1); } + private static final String REMEDY = + " Query with responseFormat=delta and advertise the features in delta-sharing-capabilities," + + " or ask your data provider to disable them."; + + private static void require(String header, ResponseFormat format, Protocol protocol) { + DeltaSharingCapabilities.requireReaderFeatures( + DeltaSharingCapabilities.declared(header), format, protocol, 7); + } + + private static void assertUnsupported( + String message, String header, ResponseFormat format, Protocol protocol) { + ApiException error = + assertThrows(ApiException.class, () -> require(header, format, protocol)); + assertEquals(400, error.getStatus()); + assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, error.getErrorCode()); + assertEquals(message, error.getMessage()); + } + @Test void queryRequiresReaderFeaturesOnlyFromClientsThatAcceptDelta() { Protocol basic = new Protocol(1, 2); Protocol columnMapping = new Protocol(2, 5); Protocol advanced = new Protocol(3, 7, Set.of("columnMapping", "deletionVectors"), Set.of("columnMapping")); + assertDoesNotThrow(() -> require(null, ResponseFormat.PARQUET, basic)); + assertDoesNotThrow(() -> require("responseformat=delta", ResponseFormat.DELTA, basic)); assertDoesNotThrow( () -> - DeltaSharingCapabilities.requireReaderFeatures( - null, ResponseFormat.PARQUET, basic)); + require( + "responseformat=delta;readerfeatures=columnmapping,deletionvectors,newfeature", + ResponseFormat.DELTA, + advanced)); assertDoesNotThrow( - () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=delta", ResponseFormat.DELTA, basic)); + () -> require("responseformat=delta", ResponseFormat.DELTA, columnMapping)); + assertDoesNotThrow(() -> require("responseformat=parquet", ResponseFormat.DELTA, advanced)); + assertDoesNotThrow(() -> require(null, ResponseFormat.DELTA, advanced)); + // Deletion vectors stay in a protocol after they are turned off, so their property decides. assertDoesNotThrow( () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=delta;readerfeatures=columnmapping,deletionvectors,newfeature", + require( + "responseformat=delta;readerfeatures=columnmapping", ResponseFormat.DELTA, advanced)); + } + + @Test + void namesTheReaderFeaturesTheClientDidNotAdvertise() { + Protocol columnMapping = new Protocol(2, 5); + Protocol advanced = + new Protocol( + 3, + 7, + Set.of("deletionVectors", "timestampNtz", "columnMapping"), + Set.of("columnMapping")); + // Every feature, once and in a fixed order, and the table version they were found in. + assertUnsupported( + "Table features columnmapping, timestampntz are found in table version: 7." + REMEDY, + "responseformat=delta", + ResponseFormat.DELTA, + advanced); + assertUnsupported( + "Table features timestampntz are found in table version: 7." + REMEDY, + "responseformat=delta;readerfeatures=notAFeature, COLUMNMAPPING", + ResponseFormat.DELTA, + advanced); + // A client that accepts only parquet cannot read a table with reader features. + assertUnsupported( + "Table features columnmapping, deletionvectors, timestampntz are found in table version:" + + " 7." + + REMEDY, + "responseformat=parquet", + ResponseFormat.PARQUET, + advanced); + assertUnsupported( + "Table features reader version 2 are found in table version: 7." + REMEDY, + "responseformat=parquet", + ResponseFormat.PARQUET, + columnMapping); + } + + @Test + void aTablePropertyThatEnablesAFeatureNeedsTheFeatureAdvertised() { + Map enabled = + Map.of( + "delta.enableDeletionVectors", "true", + "delta.columnMapping.mode", "name", + "delta.appendOnly", "true"); + ApiException error = + assertThrows( + ApiException.class, + () -> + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared("responseformat=delta"), enabled, 3)); + assertEquals( + "Table features delta.columnMapping.mode, delta.enableDeletionVectors are found in table" + + " version: 3." + + REMEDY, + error.getMessage()); + assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, error.getErrorCode()); + + // Advertised, off, absent and unrelated properties all pass. assertDoesNotThrow( () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=delta", ResponseFormat.DELTA, columnMapping)); + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared( + "responseformat=delta;readerfeatures=ColumnMapping,deletionVectors"), + enabled, + 3)); assertDoesNotThrow( () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=parquet", ResponseFormat.DELTA, advanced)); + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared("responseformat=delta"), + Map.of( + "delta.enableDeletionVectors", " false ", + "delta.columnMapping.mode", "none", + "delta.appendOnly", "true"), + 3)); + // Delta reads the off values in any case. assertDoesNotThrow( - () -> DeltaSharingCapabilities.requireReaderFeatures(null, ResponseFormat.DELTA, advanced)); - assertThrows( - ApiException.class, - () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=parquet", ResponseFormat.PARQUET, advanced)); - assertThrows( - ApiException.class, () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=parquet", ResponseFormat.PARQUET, columnMapping)); - assertThrows( - ApiException.class, - () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=delta", ResponseFormat.DELTA, advanced)); - assertThrows( - ApiException.class, + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared("responseformat=delta"), + Map.of( + "delta.enableDeletionVectors", "False", + "delta.columnMapping.mode", "NONE"), + 3)); + assertDoesNotThrow( () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=delta;readerfeatures=columnmapping", - ResponseFormat.DELTA, - advanced)); - assertThrows( - ApiException.class, + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared(null), Map.of(), 3)); + assertDoesNotThrow( () -> - DeltaSharingCapabilities.requireReaderFeatures( - "responseformat=delta;readerfeatures=notAFeature", - ResponseFormat.DELTA, - advanced)); + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared(null), null, 3)); } } diff --git a/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaKernelErrorsTest.java b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaKernelErrorsTest.java new file mode 100644 index 000000000..2a2c6577d --- /dev/null +++ b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaKernelErrorsTest.java @@ -0,0 +1,217 @@ +package io.opensharing.asset.table.delta; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertInstanceOf; +import static org.junit.jupiter.api.Assertions.assertSame; + +import io.delta.kernel.exceptions.InvalidTableException; +import io.delta.kernel.exceptions.KernelEngineException; +import io.delta.kernel.exceptions.KernelException; +import io.delta.kernel.exceptions.TableNotFoundException; +import io.delta.kernel.exceptions.UnsupportedProtocolVersionException; +import io.delta.kernel.exceptions.UnsupportedTableFeatureException; +import io.opensharing.http.ApiException; +import io.opensharing.http.ErrorCodes; +import java.io.FileNotFoundException; +import java.io.IOException; +import java.nio.file.AccessDeniedException; +import java.util.Set; +import org.junit.jupiter.api.Test; + +/** How Kernel's failures reach the recipient: by whose state they report, and in what words. */ +class DeltaKernelErrorsTest { + + private static final String TABLE = "file:/tables/my table/"; + private static final String UNREADABLE = + "Unable to access table share.lake.t: something is wrong with the table. Please contact" + + " your data provider."; + + private static void assertApiError(int status, String code, String message, Throwable actual) { + ApiException error = assertInstanceOf(ApiException.class, actual); + assertEquals(status, error.getStatus()); + assertEquals(code, error.getErrorCode()); + assertEquals(message, error.getMessage()); + } + + private static void assertUnreadable(RuntimeException failed) { + SourceTableException source = + assertInstanceOf(SourceTableException.class, DeltaKernel.classify(failed, TABLE, null)); + assertApiError(400, ErrorCodes.BAD_REQUEST, UNREADABLE, source.forRecipient("share.lake.t")); + } + + @Test + void aMissingLogIsTheSourceTablesState() { + assertUnreadable(new TableNotFoundException(TABLE)); + } + + @Test + void missingOrDeniedFilesAreTheSourceTablesState() { + assertUnreadable(new KernelEngineException("read failed", new FileNotFoundException("x"))); + assertUnreadable( + new KernelEngineException( + "read failed", new IOException("wrapped", new AccessDeniedException("x")))); + } + + @Test + void aLogKernelRejectsIsReportedInKernelsWordsWithTheProviderToContact() { + assertApiError( + 400, + ErrorCodes.BAD_REQUEST, + "Invalid table found at the table: Cannot compute snapshot. Missing delta file version 0." + + " Please contact your data provider.", + DeltaKernel.classify( + new InvalidTableException( + TABLE, "Cannot compute snapshot. Missing delta file version 0."), + TABLE, + null)); + } + + @Test + void aVersionTheTableDoesNotHaveIsReportedInKernelsWords() { + assertApiError( + 400, + ErrorCodes.BAD_REQUEST, + "Cannot load table version 9 as the latest version is 2.", + DeltaKernel.classify( + new KernelException("Cannot load table version 9 as the latest version is 2."), + TABLE, + null)); + assertApiError( + 400, + ErrorCodes.BAD_REQUEST, + "The provided timestamp 1 is too early.", + DeltaKernel.classify( + new IllegalArgumentException("The provided timestamp 1 is too early."), TABLE, null)); + } + + @Test + void unsupportedFeaturesAreNamedInAFixedOrder() { + String remedy = "This server cannot read them. Please contact your data provider."; + assertApiError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Table features futurefeature, otherfeature are found in table version: 3. " + remedy, + DeltaKernel.classify( + new UnsupportedTableFeatureException( + TABLE, Set.of("otherFeature", "futureFeature"), "read"), + TABLE, + 3L)); + assertApiError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Table features futurefeature are found in table. " + remedy, + DeltaKernel.classify( + new UnsupportedTableFeatureException(TABLE, Set.of("futureFeature"), "read"), + TABLE, + null)); + } + + @Test + void anUnsupportedReaderVersionIsNamedAsAFeature() { + assertApiError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Table features reader version 9 are found in table. This server cannot read them. Please" + + " contact your data provider.", + DeltaKernel.classify( + new UnsupportedProtocolVersionException( + TABLE, 9, 9, UnsupportedProtocolVersionException.ProtocolVersionType.READER), + TABLE, + null)); + } + + @Test + void stripsOtherLocationsWithASchemeFromKernelWords() { + assertEquals( + "Invalid table found at the table: Missing the table, the table.", + DeltaKernel.kernelError( + new KernelException( + "Invalid table found at s3a://bucket/other/table: Missing" + + " s3://bucket/%7Ealt/table/_delta_log/0.json, file:///x/y."), + TABLE, + "") + .getMessage()); + } + + @Test + void stripsTheTablePathInEveryStorageScheme() { + for (String table : + new String[] { + "s3://bucket/my tables/t/", + "s3a://bucket/my tables/t", + "abfss://container@account.dfs.core.windows.net/my tables/t", + "gs://bucket/my tables/t/", + "file:/tmp/my tables/t", + }) { + String escaped = table.replace(" ", "%20"); + String plain = table.replaceAll("/$", ""); + String encoded = java.net.URLEncoder.encode(plain, java.nio.charset.StandardCharsets.UTF_8); + for (String spelling : + new String[] {plain, plain + "/", escaped, escaped.replace(":", "%3A"), encoded}) { + ApiException error = + DeltaKernel.kernelError( + new KernelException( + "Invalid table found at " + spelling + ": no file " + spelling + "/_delta_log"), + table, + ""); + assertFalse( + error.getMessage().matches("(?s).*(bucket|container|account|/tmp|my.tables).*"), + table + " as " + spelling + " -> " + error.getMessage()); + } + } + } + + @Test + void aStorageFailureOfItsOwnStaysAServerError() { + KernelEngineException storage = + new KernelEngineException("read failed", new IOException("timeout")); + assertSame(storage, DeltaKernel.classify(storage, TABLE, null)); + } + + @Test + void aCauseChainThatLoopsEndsTheSearchForMissingFiles() { + IOException looping = new IOException("a"); + IOException other = new IOException("b", looping); + looping.initCause(other); + assertSame( + looping, + DeltaKernel.classify(new KernelEngineException("read failed", looping), TABLE, null) + .getCause()); + } + + @Test + void stripsEverySpellingOfTheTablePathFromKernelWords() { + for (String message : + new String[] { + "file:/tables/my table/: The timestamp is early.", + "/tables/my table: The timestamp is early.", + "file:/tables/my%20table/: The timestamp is early.", + "The timestamp is early.", + }) { + assertEquals( + "The timestamp is early.", + DeltaKernel.kernelError(new KernelException(message), TABLE, "").getMessage(), + message); + } + // The catalog may spell a local location with three slashes where Kernel normalizes to one. + assertEquals( + "Missing the table/_delta_log", + DeltaKernel.kernelError( + new KernelException("Missing file:/tables/my table/_delta_log"), + "file:///tables/my table/", + "") + .getMessage()); + ApiException inline = + DeltaKernel.kernelError( + new KernelException( + "No commit at /tables/my table/_delta_log/0.json or" + + " file:/tables/my%20table/_delta_log/1.json"), + TABLE, + ""); + assertEquals( + "No commit at the table/_delta_log/0.json or the table/_delta_log/1.json", + inline.getMessage()); + assertFalse(inline.getMessage().contains("tables")); + } +} diff --git a/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaTableQueryReaderTest.java b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaTableQueryReaderTest.java index 245fa9b49..b2ae9443b 100644 --- a/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaTableQueryReaderTest.java +++ b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaTableQueryReaderTest.java @@ -216,8 +216,14 @@ void startingVersionDecodesLogPathsButNotTheTableRoot() throws IOException { @Test void rejectsVersionsAfterTheLatestVersion() throws IOException { writeChanges(); - assertThrows(ApiException.class, () -> changes(5L, null, null, false)); - assertThrows(ApiException.class, () -> changes(1L, 5L, null, false)); + assertEquals( + "Provided Start version(5) for reading change data is invalid. Start version cannot be" + + " greater than the latest version of the table(4).", + assertThrows(ApiException.class, () -> changes(5L, null, null, false)).getMessage()); + assertEquals( + "Provided End version(5) for reading change data is invalid. End version cannot be" + + " greater than the latest version of the table(4).", + assertThrows(ApiException.class, () -> changes(1L, 5L, null, false)).getMessage()); } @Test @@ -248,18 +254,39 @@ void changeDataFeedResolvesTimestampsAndHistoricalMetadata() throws IOException true); assertTrue(lines.get(1).contains("\"version\":1"), lines.get(1)); assertEquals(List.of("cdf c 1", "remove b 2"), describe(lines.subList(2, lines.size()))); - // An end after the latest version is capped; the range then reaches CDF being disabled. - assertThrows(ApiException.class, () -> changeDataFeed(0L, null, 9L, null, null, false)); + // An end after the latest version is rejected rather than capped. + ApiException afterLatest = + assertThrows(ApiException.class, () -> changeDataFeed(0L, null, 9L, null, null, false)); + assertEquals( + "Provided End version(9) for reading change data is invalid. End version cannot be" + + " greater than the latest version of the table(4).", + afterLatest.getMessage()); } @Test void changeDataFeedRejectsInvalidRanges() throws IOException { // The table written in setup never enabled the Change Data Feed. - assertThrows(ApiException.class, () -> changeDataFeed(0L, null, null, null, null, false)); + SourceTableException unrecorded = + assertThrows( + SourceTableException.class, + () -> changeDataFeed(0L, null, null, null, null, false)); + assertEquals( + "Unable to access change data feed for share.schema.table. CDF is not enabled on the" + + " original delta table for version 0. Please contact your data provider.", + unrecorded.forRecipient("share.schema.table").getMessage()); writeChangeDataFeed(); - assertThrows(ApiException.class, () -> changeDataFeed(null, null, null, null, null, false)); - assertThrows(ApiException.class, () -> changeDataFeed(2L, null, 1L, null, null, false)); - assertThrows(ApiException.class, () -> changeDataFeed(5L, null, null, null, null, false)); + assertEquals( + "CDF range from startingVersion 2 to endingVersion 1 was invalid. End cannot be before" + + " start.", + assertThrows( + ApiException.class, () -> changeDataFeed(2L, null, 1L, null, null, false)) + .getMessage()); + assertEquals( + "Provided Start version(5) for reading change data is invalid. Start version cannot be" + + " greater than the latest version of the table(4).", + assertThrows( + ApiException.class, () -> changeDataFeed(5L, null, null, null, null, false)) + .getMessage()); } @Test diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java index a2d27a2a9..c52c983a7 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java @@ -1,5 +1,8 @@ package io.opensharing.protocol; +import static org.junit.jupiter.api.Assertions.assertFalse; + +import io.opensharing.TestServer.Response; import java.io.IOException; import java.io.UncheckedIOException; import java.nio.file.Files; @@ -7,6 +10,7 @@ import java.nio.file.attribute.FileTime; import java.time.Duration; import java.time.Instant; +import java.util.List; import java.util.Properties; import org.junit.jupiter.api.BeforeAll; import org.junit.jupiter.api.io.TempDir; @@ -18,8 +22,16 @@ * {@code main.ops.events} with 2 commits and no data files. Commit {@code n} of each table is * timestamped 2024-01-01T00:00:00Z plus {@code n} hours. Table {@code t} has metadata id {@code t} * and one {@code long} column, {@code id}. {@code main.lake.unwritten} is a Delta table with no - * log, {@code main.lake.raw} has no format, and {@code main.lake.future} requires a reader feature - * Kernel does not know. + * log, {@code main.lake.raw} has no format, {@code main.lake.future} requires a reader feature + * Kernel does not know, {@code main.lake.gapped} has a log that starts at version 1, so its first + * commit is missing, {@code main.lake.noncontiguous} has commits 0 and 2, so version 1 is + * missing, {@code main.lake.invalidlog}, in a directory with a space in its name, enables in-commit + * timestamps but its first commit has no CommitInfo, and {@code main.lake.futuresince} needs a + * reader feature Kernel does not know at version 0 but not at its latest. {@code main.lake.cm} + * enables column mapping by name and {@code main.lake.dv} deletion vectors, {@code + * main.lake.propsoff} has both turned off, and {@code main.lake.cmlater} records change data and + * enables column mapping from version 1. {@code main.lake.cdfmid} records change data at version 0, + * commits no change at version 1, and stops recording at version 2. */ abstract class LocalDeltaTableSupport extends ProtocolApiSupport { @@ -39,9 +51,40 @@ abstract class LocalDeltaTableSupport extends ProtocolApiSupport { "{\"protocol\":{\"minReaderVersion\":3,\"minWriterVersion\":7," + "\"readerFeatures\":[\"futureFeature\"],\"writerFeatures\":[\"futureFeature\"]}}\n"; private static final String COMMIT_INFO_ACTION = "{\"commitInfo\":{}}\n"; + private static final String ICT_PROTOCOL_ACTION = + "{\"protocol\":{\"minReaderVersion\":1,\"minWriterVersion\":7," + + "\"writerFeatures\":[\"inCommitTimestamp\"]}}\n"; + private static final String ICT_METADATA_ACTION = + METADATA_ACTION.formatted("invalidlog").replace( + "\"configuration\":{}", + "\"configuration\":{\"delta.enableInCommitTimestamps\":\"true\"," + + "\"delta.inCommitTimestampEnablementVersion\":\"0\"," + + "\"delta.inCommitTimestampEnablementTimestamp\":\"1704067200000\"}"); + + private static final String CM_PROTOCOL_ACTION = + "{\"protocol\":{\"minReaderVersion\":2,\"minWriterVersion\":5," + + "\"readerFeatures\":[\"columnMapping\"],\"writerFeatures\":[\"columnMapping\"]}}\n"; + private static final String DV_PROTOCOL_ACTION = + "{\"protocol\":{\"minReaderVersion\":3,\"minWriterVersion\":7," + + "\"readerFeatures\":[\"deletionVectors\"],\"writerFeatures\":[\"deletionVectors\"]}}\n"; + private static final String LEGACY_CM_PROTOCOL_ACTION = + "{\"protocol\":{\"minReaderVersion\":2,\"minWriterVersion\":5}}\n"; + private static final String CM_CONFIGURATION = + "\"delta.columnMapping.mode\":\"name\",\"delta.columnMapping.maxColumnId\":\"1\""; + private static final String CDF_CONFIGURATION = "\"delta.enableChangeDataFeed\":\"true\""; + + /** A directory name with a space, which a table path spells two ways: raw and URI-escaped. */ + protected static final String INVALID_LOG_DIRECTORY = "invalid log"; @TempDir static Path tables; + /** Metadata for table {@code name} with Delta properties {@code configuration}, as JSON. */ + private static String metadataWith(String name, String configuration) { + return METADATA_ACTION + .formatted(name) + .replace("\"configuration\":{}", "\"configuration\":{" + configuration + "}"); + } + @BeforeAll static void startLocalDeltaServer() { String orders = deltaTable("orders", 3); @@ -51,6 +94,64 @@ static void startLocalDeltaServer() { write( "future/_delta_log/%020d.json".formatted(0), FUTURE_PROTOCOL_ACTION + METADATA_ACTION.formatted("future")); + // Column mapping by name, and deletion vectors, are enabled by table properties. + write( + "cm/_delta_log/%020d.json".formatted(0), + CM_PROTOCOL_ACTION + metadataWith("cm", CM_CONFIGURATION)); + write( + "dv/_delta_log/%020d.json".formatted(0), + DV_PROTOCOL_ACTION + metadataWith("dv", "\"delta.enableDeletionVectors\":\"true\"")); + // Both properties at their off values, deletion vectors still in the protocol, and a property + // no feature depends on. + write( + "propsoff/_delta_log/%020d.json".formatted(0), + DV_PROTOCOL_ACTION + + metadataWith( + "propsoff", + "\"delta.enableDeletionVectors\":\"false\",\"delta.columnMapping.mode\":\"none\"," + + "\"delta.appendOnly\":\"true\"")); + // Plain and recording change data at version 0; column mapping by name from version 1 on. + write( + "cmlater/_delta_log/%020d.json".formatted(0), + PROTOCOL_ACTION + metadataWith("cmlater", CDF_CONFIGURATION) + COMMIT_INFO_ACTION); + write( + "cmlater/_delta_log/%020d.json".formatted(1), + LEGACY_CM_PROTOCOL_ACTION + + metadataWith("cmlater", CDF_CONFIGURATION + "," + CM_CONFIGURATION) + + COMMIT_INFO_ACTION); + // Change data recorded at version 0, a commit that changes nothing at version 1, and a + // metaData at version 2 that stops recording it. + write( + "cdfmid/_delta_log/%020d.json".formatted(0), + PROTOCOL_ACTION + + METADATA_ACTION + .formatted("cdfmid") + .replace( + "\"configuration\":{}", + "\"configuration\":{\"delta.enableChangeDataFeed\":\"true\"}") + + COMMIT_INFO_ACTION); + write("cdfmid/_delta_log/%020d.json".formatted(1), COMMIT_INFO_ACTION); + write( + "cdfmid/_delta_log/%020d.json".formatted(2), + METADATA_ACTION.formatted("cdfmid") + COMMIT_INFO_ACTION); + appendCommit("gapped", 1); + // Commits 0 and 2 with version 1 missing, a gap Kernel rejects as non-contiguous. + write( + "noncontiguous/_delta_log/%020d.json".formatted(0), + PROTOCOL_ACTION + METADATA_ACTION.formatted("noncontiguous") + COMMIT_INFO_ACTION); + write("noncontiguous/_delta_log/%020d.json".formatted(2), COMMIT_INFO_ACTION); + // In-commit timestamps enabled, with a first commit that carries no CommitInfo: Kernel calls + // the log invalid without any file being missing. + write( + INVALID_LOG_DIRECTORY + "/_delta_log/%020d.json".formatted(0), + ICT_PROTOCOL_ACTION + ICT_METADATA_ACTION); + // A reader feature Kernel does not know at version 0, which the latest version does not need. + write( + "futuresince/_delta_log/%020d.json".formatted(0), + FUTURE_PROTOCOL_ACTION + METADATA_ACTION.formatted("futuresince")); + write( + "futuresince/_delta_log/%020d.json".formatted(1), + PROTOCOL_ACTION + METADATA_ACTION.formatted("futuresince") + COMMIT_INFO_ACTION); String catalog = """ principals: @@ -101,6 +202,51 @@ static void startLocalDeltaServer() { subtype: MANAGED storageLocation: %s format: delta + - identifier: main.lake.gapped + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.noncontiguous + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.invalidlog + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.futuresince + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.cm + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.dv + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.propsoff + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.cmlater + attributes: + subtype: MANAGED + storageLocation: %s + format: delta + - identifier: main.lake.cdfmid + attributes: + subtype: MANAGED + storageLocation: %s + format: delta """ .formatted( orders, @@ -109,17 +255,40 @@ static void startLocalDeltaServer() { events, location("unwritten"), location("raw"), - location("future")); + location("future"), + location("gapped"), + location("noncontiguous"), + unescapedLocation(INVALID_LOG_DIRECTORY), + location("futuresince"), + location("cm"), + location("dv"), + location("propsoff"), + location("cmlater"), + location("cdfmid")); Properties properties = new Properties(); properties.setProperty("catalog.local.file", write("local-catalog.yml", catalog).toString()); restartServer(properties); } + /** Asserts that {@code response} does not name where the tables are stored, in any spelling. */ + protected static void assertNoStoragePath(Response response) { + List spellings = + List.of(tables.toString(), tables.toUri().toString(), INVALID_LOG_DIRECTORY, "%20"); + for (String path : spellings) { + assertFalse(response.text().contains(path), response.text()); + } + } + /** The storage location of table {@code name}. */ protected static String location(String name) { return tables.resolve(name).toUri().toString(); } + /** The storage location of table {@code name} with its spaces as they are, not URI-escaped. */ + private static String unescapedLocation(String name) { + return "file:" + tables.resolve(name); + } + private static String deltaTable(String name, int commits) { return deltaTable(name, commits, true); } diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolApiSupport.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolApiSupport.java index 8fd259458..1c2de931d 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolApiSupport.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolApiSupport.java @@ -27,6 +27,14 @@ public abstract class ProtocolApiSupport { protected static TestServer server; + /** Asserts the whole answer: HTTP status, protocol error code and message. */ + protected static void assertError( + int status, String errorCode, String message, Response response) { + assertEquals(status, response.status(), response.text()); + assertEquals(errorCode, response.errorCode(), response.text()); + assertEquals(message, response.body().path("message").asText(), response.text()); + } + @BeforeAll static void startServer() { server = TestServer.start(); diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesIntegrationTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesIntegrationTest.java index 4faede2f1..5eeadd11b 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesIntegrationTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesIntegrationTest.java @@ -44,14 +44,20 @@ void queriesChangeDataFeedOfCdfTable() { String delta = ok(changes(endpoint + range, bearer, "responseformat=delta"), "0"); assertEquals(changes, count(delta, "file"), delta); - // Version 4 stops recording change data after the response has begun, so its error ends it. - String off = - ok(changes(endpoint + "?startingVersion=0", bearer, "includeendstreamaction=true"), "0"); - String last = off.substring(off.stripTrailing().lastIndexOf('\n') + 1); - assertTrue(last.startsWith("{\"endStreamAction\":{\"errorMessage\":"), last); - assertTrue(last.contains("not recorded for version [4]"), last); - // An end after the latest version is capped rather than rejected. - ok(changes(endpoint + "?startingVersion=5&endingVersion=1000", bearer, null), "5"); + // Version 4 stops recording change data, which is found before the response begins, however + // the range is bounded. + for (String bounds : + new String[] {"startingVersion=0", "startingTimestamp=2000-01-01T00:00:00Z"}) { + Response off = changes(endpoint + "?" + bounds, bearer, "includeendstreamaction=true"); + assertEquals(403, off.status(), off.text()); + assertEquals(ErrorCodes.PERMISSION_DENIED, off.errorCode(), off.text()); + assertTrue( + off.text().contains("CDF is not enabled on the original delta table for version 4"), + off.text()); + } + // An end after the latest version is rejected rather than capped. + assertInvalid(changes(endpoint + "?startingVersion=5&endingVersion=1000", bearer, null)); + ok(changes(endpoint + "?startingVersion=5&endingVersion=5", bearer, null), "5"); // A range that ends before it starts is rejected. assertInvalid(changes(endpoint + "?startingVersion=1&endingVersion=0", bearer, null)); } @@ -81,8 +87,13 @@ private static void rejectsChangeDataFeed(String share, String catalogName, Stri String endpoint = endpoint(share, sharedAs); Response unrecorded = changes(endpoint + "?startingVersion=0", bearer, null); - assertInvalid(unrecorded); - assertTrue(unrecorded.text().contains("change data was not recorded"), unrecorded.text()); + assertEquals(403, unrecorded.status(), unrecorded.text()); + assertEquals(ErrorCodes.PERMISSION_DENIED, unrecorded.errorCode()); + assertTrue( + unrecorded + .text() + .contains("CDF is not enabled on the original delta table for version 0"), + unrecorded.text()); // A starting version or timestamp is required. assertInvalid(changes(endpoint, bearer, null)); } diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesTest.java index 6c1c14640..b1d2fabba 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableChangesTest.java @@ -1,11 +1,9 @@ package io.opensharing.protocol; import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertTrue; import io.opensharing.TestServer.Response; import io.opensharing.http.ErrorCodes; -import java.util.List; import org.junit.jupiter.api.Test; /** @@ -24,16 +22,109 @@ void validatesChangeDataFeedRequests() { grant("table-cdf", "table-cdf-partner"); String changes = PROTOCOL + "/shares/TABLE-CDF/schemas/OPS/tables/EVENTS/changes"; - // A table that does not record its Change Data Feed is INVALID_PARAMETER_VALUE. - Response unrecorded = server.get(changes + "?startingVersion=0", bearer); - assertEquals(400, unrecorded.status(), unrecorded.text()); - assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, unrecorded.errorCode()); - assertTrue(unrecorded.text().contains("change data was not recorded"), unrecorded.text()); + // A table that does not record its Change Data Feed is the source table's own state, and the + // recipient is told to contact the data provider. + assertError( + 403, + ErrorCodes.PERMISSION_DENIED, + "Unable to access change data feed for table-cdf.ops.events. CDF is not enabled on the" + + " original delta table for version 0. Please contact your data provider.", + server.get(changes + "?startingVersion=0", bearer)); - // A start is required, and must be a version or an ISO-8601 timestamp. - for (String invalid : List.of("", "?startingTimestamp=yesterday", "?startingVersion=one")) { - assertEquals(400, server.get(changes + invalid, bearer).status(), invalid); - } + // A start is required, once, and must be a version or an ISO-8601 timestamp. + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "No startingVersion or startingTimestamp provided for CDF read. Set one of them on the" + + " request's cdfOptions to bound the CDC range.", + server.get(changes, bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "startingTimestamp must be an ISO-8601 UTC timestamp", + server.get(changes + "?startingTimestamp=yesterday", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "startingVersion is not a valid number.", + server.get(changes + "?startingVersion=one", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "endingVersion is not a valid number.", + server.get(changes + "?startingVersion=0&endingVersion=last", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Multiple starting arguments provided for CDF read. Please provide one of either" + + " startingTimestamp or startingVersion.", + server.get(changes + "?startingVersion=0&startingTimestamp=2024-01-01T00:00:00Z", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Multiple ending arguments provided for CDF read. Please provide one of either" + + " endingTimestamp or endingVersion.", + server.get( + changes + "?startingVersion=0&endingVersion=1&endingTimestamp=2024-01-01T00:00:00Z", + bearer)); + + // A negative bound, and a range that ends before it starts. + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "startingVersion cannot be negative.", + server.get(changes + "?startingVersion=-1", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "endingVersion cannot be negative.", + server.get(changes + "?startingVersion=0&endingVersion=-1", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "CDF range from startingVersion 1 to endingVersion 0 was invalid. End cannot be before" + + " start.", + server.get(changes + "?startingVersion=1&endingVersion=0", bearer)); + + // A bound after the latest version, or the latest commit time. + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Provided Start version(9) for reading change data is invalid. Start version cannot be" + + " greater than the latest version of the table(1).", + server.get(changes + "?startingVersion=9", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Provided End version(9) for reading change data is invalid. End version cannot be" + + " greater than the latest version of the table(1).", + server.get(changes + "?startingVersion=0&endingVersion=9", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "The provided timestamp(2100-01-01T00:00:00Z) is after the latest table version" + + " available to this table (2024-01-01T01:00:00Z). Please use a timestamp less than" + + " or equal to 2024-01-01T01:00:00Z", + server.get(changes + "?startingVersion=0&endingTimestamp=2100-01-01T00:00:00Z", bearer)); + + // A start timestamp before the first commit starts at version 0, and an end timestamp before + // it is Kernel's report, without the storage path. + assertError( + 403, + ErrorCodes.PERMISSION_DENIED, + "Unable to access change data feed for table-cdf.ops.events. CDF is not enabled on the" + + " original delta table for version 0. Please contact your data provider.", + server.get(changes + "?startingTimestamp=2000-01-01T00:00:00Z", bearer)); + Response early = + server.get(changes + "?startingVersion=0&endingTimestamp=2000-01-01T00:00:00Z", bearer); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "The provided timestamp 946684800000 ms (2000-01-01T00:00:00Z) is before the earliest" + + " available version 0. Please use a timestamp greater than or equal to" + + " 1704067200000 ms (2024-01-01T00:00:00Z).", + early); + assertNoStoragePath(early); // A table in an ungranted share is 404, not 403. String hiddenChanges = PROTOCOL + "/shares/hidden-cdf/schemas/sales/tables/customers/changes"; diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataIntegrationTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataIntegrationTest.java index 4d7714829..d7fa10249 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataIntegrationTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataIntegrationTest.java @@ -58,8 +58,8 @@ void queriesLatestAndHistoricalMetadataForTable1() { // Historical version 0, and as of the first commit time, return that snapshot. assertVersion("0", metadata(endpoint + "?version=0", bearer, null)); assertVersion("0", metadata(endpoint + "?timestamp=2021-05-04T17:24:06Z", bearer, null)); - // As of before version 0 is INVALID_PARAMETER_VALUE. - assertInvalid(metadata(endpoint + "?timestamp=1970-01-01T00:00:00Z", bearer, null)); + // As of before version 0 is Kernel's report. + assertBadRequest(metadata(endpoint + "?timestamp=1970-01-01T00:00:00Z", bearer, null)); // version and timestamp together are mutually exclusive. assertInvalid(metadata(endpoint + "?version=1×tamp=2021-05-04T17:24:06Z", bearer, null)); } @@ -120,6 +120,12 @@ private static void assertVersion(String expected, Response response) { assertEquals(expected, response.headers().get("Delta-Table-Version")); } + /** Kernel's report that the table has no such version or timestamp. */ + private static void assertBadRequest(Response response) { + assertEquals(400, response.status()); + assertEquals(ErrorCodes.BAD_REQUEST, response.errorCode()); + } + private static void assertInvalid(Response response) { assertEquals(400, response.status()); assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, response.errorCode()); diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataTest.java index bd2a6243f..07b83238a 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataTest.java @@ -79,8 +79,11 @@ void queriesGrantedTableMetadata() { assertEquals(200, atTimestamp.status()); assertEquals("1", atTimestamp.headers().get("Delta-Table-Version")); - assertInvalid(metadata(orders + "?version=9", bearer, null)); - assertInvalid(metadata(orders + "?version=1×tamp=2024-01-01T01:30:00Z", bearer, null)); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "Cannot load table version 9 as it does not exist. The latest available version is 2.", + metadata(orders + "?version=9", bearer, null)); assertInvalid(metadata(orders + "?timestamp=not-a-timestamp", bearer, null)); // A table in an ungranted share is 404, not 403. @@ -94,33 +97,38 @@ void queriesGrantedTableMetadata() { } @Test - void reportsADeltaTableWithoutALogAsACatalogError() { - createShare("unwritten-metadata"); - addObject("unwritten-metadata", "TABLE", "main.lake.unwritten", "lake.unwritten"); - String bearer = createAndActivateRecipient("unwritten-metadata-partner"); - grant("unwritten-metadata", "unwritten-metadata-partner"); - - Response unwritten = - metadata( - PROTOCOL + "/shares/unwritten-metadata/schemas/lake/tables/unwritten/metadata", - bearer, - null); - assertEquals(502, unwritten.status()); - assertEquals(ErrorCodes.CATALOG_ERROR, unwritten.errorCode()); - } - - @Test - void reportsAReaderFeatureKernelCannotReadWithoutTheStoragePath() { - createShare("future-metadata"); - addObject("future-metadata", "TABLE", "main.lake.future", "lake.future"); - String bearer = createAndActivateRecipient("future-metadata-partner"); - grant("future-metadata", "future-metadata-partner"); - - Response future = - metadata( - PROTOCOL + "/shares/future-metadata/schemas/lake/tables/future/metadata", bearer, null); - assertInvalid(future); - assertFalse(future.body().toString().contains(tables.toString())); + void answersVersionAndTimestampMistakes() { + createShare("mistakes-metadata"); + addObject("mistakes-metadata", "TABLE", "main.sales.orders", "sales.orders"); + String bearer = createAndActivateRecipient("mistakes-metadata-partner"); + grant("mistakes-metadata", "mistakes-metadata-partner"); + String orders = PROTOCOL + "/shares/mistakes-metadata/schemas/sales/tables/orders/metadata"; + + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Please only provide one of: version,timestamp", + metadata(orders + "?version=1×tamp=2024-01-01T01:30:00Z", bearer, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "version cannot be negative.", + metadata(orders + "?version=-1", bearer, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "version is not a valid number.", + metadata(orders + "?version=latest", bearer, null)); + // A timestamp before the first commit is Kernel's report, without the storage path. + Response early = metadata(orders + "?timestamp=2000-01-01T00:00:00Z", bearer, null); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "The provided timestamp 946684800000 ms (2000-01-01T00:00:00Z) is before the earliest" + + " available version 0. Please use a timestamp greater than or equal to" + + " 1704067200000 ms (2024-01-01T00:00:00Z).", + early); + assertNoStoragePath(early); } private static Response metadata(String path, String bearer, String capabilities) { diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTablePropertiesTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTablePropertiesTest.java new file mode 100644 index 000000000..db7e57f3d --- /dev/null +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTablePropertiesTest.java @@ -0,0 +1,177 @@ +package io.opensharing.protocol; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import com.linecorp.armeria.common.HttpMethod; +import io.opensharing.TestServer.Response; +import io.opensharing.http.ErrorCodes; +import org.junit.jupiter.api.Test; + +/** + * A table whose Delta properties enable a reader feature the client did not advertise is not + * served: column mapping by name, and deletion vectors, are only servable to a client that + * advertises them. The answer names the properties, and the version they were found in. + */ +class ProtocolTablePropertiesTest extends LocalDeltaTableSupport { + + private static final String REMEDY = + " Query with responseFormat=delta and advertise the features in delta-sharing-capabilities," + + " or ask your data provider to disable them."; + private static final String DELTA = "responseformat=delta"; + + @Test + void rejectsUnadvertisedColumnMappingOnEveryAnswer() { + String cm = shared("cm-table", "cm"); + String bearer = recipient("cm-table"); + String message = + "Table features delta.columnMapping.mode are found in table version: 0." + REMEDY; + + for (Response answer : + new Response[] { + server.get(cm + "/metadata", bearer), + query(cm, bearer, null), + query(cm, bearer, DELTA), + query(cm, bearer, DELTA + ";readerfeatures=deletionvectors") + }) { + assertError(400, ErrorCodes.INVALID_PARAMETER_VALUE, message, answer); + assertNoStoragePath(answer); + } + + // A client that advertises columnMapping, in any case, is served. + for (String advertised : new String[] {"columnmapping", "columnMapping", "COLUMNMAPPING"}) { + Response served = query(cm, bearer, DELTA + ";readerfeatures=" + advertised); + assertEquals(200, served.status(), served.text()); + assertEquals("0", served.headers().get("Delta-Table-Version")); + } + } + + @Test + void rejectsUnadvertisedDeletionVectors() { + String dv = shared("dv-table", "dv"); + String bearer = recipient("dv-table"); + String message = + "Table features delta.enableDeletionVectors are found in table version: 0." + REMEDY; + + assertError( + 400, ErrorCodes.INVALID_PARAMETER_VALUE, message, server.get(dv + "/metadata", bearer)); + assertError(400, ErrorCodes.INVALID_PARAMETER_VALUE, message, query(dv, bearer, DELTA)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + message, + query(dv, bearer, DELTA + ";readerfeatures=columnmapping")); + + Response served = query(dv, bearer, DELTA + ";readerfeatures=deletionvectors"); + assertEquals(200, served.status(), served.text()); + } + + @Test + void servesATableWhosePropertiesAreOffOrUnrelated() { + String propsoff = shared("props-off", "propsoff"); + String bearer = recipient("props-off"); + + // Deletion vectors stay in the protocol after they are turned off, which does not block a + // client that did not advertise them. + assertEquals(200, server.get(propsoff + "/metadata", bearer).status()); + Response served = query(propsoff, bearer, DELTA); + assertEquals(200, served.status(), served.text()); + } + + @Test + void checksTheVersionOfASnapshotItServes() { + String cmlater = shared("cm-later", "cmlater"); + String bearer = recipient("cm-later"); + + // Version 0 has no column mapping, and version 1 does. + assertEquals(200, server.get(cmlater + "/metadata?version=0", bearer).status()); + assertEquals(200, query(cmlater, bearer, "{\"version\":0}", DELTA).status()); + String atVersion1 = + "Table features delta.columnMapping.mode are found in table version: 1." + REMEDY; + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + atVersion1, + server.get(cmlater + "/metadata", bearer)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + atVersion1, + server.get(cmlater + "/metadata?version=1", bearer)); + assertError( + 400, ErrorCodes.INVALID_PARAMETER_VALUE, atVersion1, query(cmlater, bearer, "{}", DELTA)); + } + + @Test + void checksTheMetadataOfEveryCommitOfAChangeFeed() { + String cmlater = shared("cm-changes", "cmlater"); + String bearer = recipient("cm-changes"); + String atVersion1 = + "Table features delta.columnMapping.mode are found in table version: 1." + REMEDY; + + // The range starts before column mapping is enabled, so its header is plain and only the + // metadata that version 1 commits carries it. The range is read whole before the response + // begins, so the error is the response's status. + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + atVersion1, + server.call( + HttpMethod.GET, + cmlater + "/changes?startingVersion=0&includeHistoricalMetadata=true", + bearer, + null, + "delta-sharing-capabilities", + DELTA)); + + // A range that starts at version 1 has column mapping in its header. + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + atVersion1, + server.call( + HttpMethod.GET, + cmlater + "/changes?startingVersion=1", + bearer, + null, + "delta-sharing-capabilities", + DELTA)); + Response advertised = + server.call( + HttpMethod.GET, + cmlater + "/changes?startingVersion=0", + bearer, + null, + "delta-sharing-capabilities", + DELTA + ";readerfeatures=columnmapping"); + assertEquals(200, advertised.status(), advertised.text()); + } + + /** Shares table {@code lake.} in share {@code share}, and returns its endpoint. */ + private String shared(String share, String table) { + createShare(share); + addObject(share, "TABLE", "main.lake." + table, "lake." + table); + return PROTOCOL + "/shares/" + share + "/schemas/lake/tables/" + table; + } + + private String recipient(String share) { + String bearer = createAndActivateRecipient(share + "-partner"); + grant(share, share + "-partner"); + return bearer; + } + + private static Response query(String table, String bearer, String capabilities) { + return query(table, bearer, "{}", capabilities); + } + + private static Response query(String table, String bearer, String body, String capabilities) { + return capabilities == null + ? server.post(table + "/query", bearer, body) + : server.call( + HttpMethod.POST, + table + "/query", + bearer, + body, + "delta-sharing-capabilities", + capabilities); + } +} diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryIntegrationTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryIntegrationTest.java index ab88ae58d..e1869dd7a 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryIntegrationTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryIntegrationTest.java @@ -61,8 +61,8 @@ void queriesLatestAndHistoricalFilesForTable1() { assertVersion("0", query(endpoint, bearer, "{\"version\":0}", null)); assertVersion( "0", query(endpoint, bearer, "{\"timestamp\":\"2021-05-04T17:24:06Z\"}", null)); - // As of before version 0 is INVALID_PARAMETER_VALUE. - assertInvalid(query(endpoint, bearer, "{\"timestamp\":\"1970-01-01T00:00:00Z\"}", null)); + // As of before version 0 is Kernel's report. + assertBadRequest(query(endpoint, bearer, "{\"timestamp\":\"1970-01-01T00:00:00Z\"}", null)); // version and timestamp together are mutually exclusive. assertInvalid( query(endpoint, bearer, "{\"version\":1,\"timestamp\":\"2021-05-04T17:24:06Z\"}", null)); @@ -127,8 +127,8 @@ private static void queryCloudTableFiles( assertVersion("0", historical); assertEquals( 2, historical.text().split("\"version\":0", -1).length - 1); - // A version after the latest is INVALID_PARAMETER_VALUE. - assertInvalid(query(endpoint, bearer, "{\"version\":1}", null)); + // A version after the latest is Kernel's report. + assertBadRequest(query(endpoint, bearer, "{\"version\":1}", null)); } private static void assertParquetQuery(String ndjson) { @@ -174,6 +174,12 @@ private static void assertVersion(String expected, Response response) { assertEquals(expected, response.headers().get("Delta-Table-Version")); } + /** Kernel's report that the table has no such version or timestamp. */ + private static void assertBadRequest(Response response) { + assertEquals(400, response.status()); + assertEquals(ErrorCodes.BAD_REQUEST, response.errorCode()); + } + private static void assertInvalid(Response response) { assertEquals(400, response.status()); assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, response.errorCode()); diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryTest.java index d2d15af82..c45e60a16 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableQueryTest.java @@ -77,9 +77,11 @@ void queriesGrantedTable() { assertEquals(200, atTimestamp.status()); assertEquals("0", atTimestamp.headers().get("Delta-Table-Version")); - assertInvalid(query(events, bearer, "{\"version\":9}", null, null)); - String both = "{\"version\":1,\"timestamp\":\"2024-01-01T00:30:00Z\"}"; - assertInvalid(query(events, bearer, both, null, null)); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "Cannot load table version 9 as it does not exist. The latest available version is 1.", + query(events, bearer, "{\"version\":9}", null, null)); assertInvalid(query(events, bearer, "{\"timestamp\":\"not-a-timestamp\"}", null, null)); // A table in an ungranted share is 404, not 403. @@ -94,6 +96,69 @@ void queriesGrantedTable() { assertEquals(ErrorCodes.RESOURCE_DOES_NOT_EXIST, hidden.errorCode()); } + @Test + void answersQueryMistakes() { + createShare("query-mistakes"); + addObject("query-mistakes", "TABLE", "main.ops.events", "ops.events"); + String bearer = createAndActivateRecipient("query-mistakes-partner"); + grant("query-mistakes", "query-mistakes-partner"); + String events = PROTOCOL + "/shares/query-mistakes/schemas/ops/tables/events/query"; + String oneOf = "Please only provide one of: version,timestamp,startingVersion"; + + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + oneOf, + query( + events, + bearer, + "{\"version\":1,\"timestamp\":\"2024-01-01T00:30:00Z\"}", + null, + null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + oneOf, + query(events, bearer, "{\"version\":1,\"startingVersion\":0}", null, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "table version cannot be negative.", + query(events, bearer, "{\"version\":-1}", null, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "startingVersion cannot be negative.", + query(events, bearer, "{\"startingVersion\":-1}", null, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "endingVersion cannot be negative.", + query(events, bearer, "{\"startingVersion\":0,\"endingVersion\":-1}", null, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "startingVersion(1) must be smaller than or equal to endingVersion(0).", + query(events, bearer, "{\"startingVersion\":1,\"endingVersion\":0}", null, null)); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Provided Start version(9) for reading change data is invalid. Start version cannot be" + + " greater than the latest version of the table(1).", + query(events, bearer, "{\"startingVersion\":9}", null, null)); + // A timestamp before the first commit is Kernel's report, without the storage path. + Response early = + query(events, bearer, "{\"timestamp\":\"2000-01-01T00:00:00Z\"}", null, null); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "The provided timestamp 946684800000 ms (2000-01-01T00:00:00Z) is before the earliest" + + " available version 0. Please use a timestamp greater than or equal to" + + " 1704067200000 ms (2024-01-01T00:00:00Z).", + early); + assertNoStoragePath(early); + } + private static Response query( String path, String bearer, String body, String capabilities, String fileIdHash) { List headers = new ArrayList<>(); diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionIntegrationTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionIntegrationTest.java index d7e3824cd..7d582f9f5 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionIntegrationTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionIntegrationTest.java @@ -38,7 +38,7 @@ void queriesLatestAndTimestampVersionsForTable1() { assertVersion("2", latest); assertTrue(latest.body().isMissingNode()); assertVersion("0", version(endpoint, bearer, "1970-01-01T00:00:00Z")); - assertInvalid(version(endpoint, bearer, "2099-01-01T00:00:00Z")); + assertBadRequest(version(endpoint, bearer, "2099-01-01T00:00:00Z")); assertInvalid(version(endpoint, bearer, "not-a-timestamp")); } @@ -56,7 +56,7 @@ void queriesAtOrAfterTimestampsOnTheStartingTimestampTable() { assertVersion("3", version(endpoint, bearer, "2023-05-09T08:32:55.517Z")); assertVersion("4", version(endpoint, bearer, "2023-05-09T08:45:00Z")); assertVersion("5", version(endpoint, bearer, "2023-05-09T09:09:58.088Z")); - assertInvalid(version(endpoint, bearer, "2023-05-09T10:00:00Z")); + assertBadRequest(version(endpoint, bearer, "2023-05-09T10:00:00Z")); } @Test @@ -90,7 +90,7 @@ private static void queryCloudTableVersions(String share, String catalogName, St String header = latest.headers().get("Delta-Table-Version"); assertTrue(header != null && Long.parseLong(header) >= 0, "latest version was " + header); assertVersion("0", version(endpoint, bearer, "1970-01-01T00:00:00Z")); - assertInvalid(version(endpoint, bearer, "2099-01-01T00:00:00Z")); + assertBadRequest(version(endpoint, bearer, "2099-01-01T00:00:00Z")); } private static Response version(String path, String bearer, String startingTimestamp) { @@ -106,6 +106,12 @@ private static void assertVersion(String expected, Response response) { assertEquals(expected, response.headers().get("Delta-Table-Version")); } + /** Kernel's report that the table has no such version or timestamp. */ + private static void assertBadRequest(Response response) { + assertEquals(400, response.status()); + assertEquals(ErrorCodes.BAD_REQUEST, response.errorCode()); + } + private static void assertInvalid(Response response) { assertEquals(400, response.status()); assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, response.errorCode()); diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionTest.java index 04cf37309..bb732dd07 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableVersionTest.java @@ -1,13 +1,13 @@ package io.opensharing.protocol; import static org.junit.jupiter.api.Assertions.assertEquals; -import static org.junit.jupiter.api.Assertions.assertFalse; import static org.junit.jupiter.api.Assertions.assertTrue; import io.opensharing.TestServer.Response; import io.opensharing.http.ErrorCodes; import java.net.URLEncoder; import java.nio.charset.StandardCharsets; +import java.util.List; import org.junit.jupiter.api.Test; /** Query Table Version through the local catalog and Kernel, on local Delta logs. */ @@ -37,12 +37,21 @@ void queriesAGrantedTableVersion() { assertVersion("2", version(salaries, bearer, "2024-01-01T01:30:00Z")); assertVersion("3", version(salaries, bearer, null)); + // A timestamp after the latest commit is Kernel's report, in Kernel's words. Response afterLatest = version(salaries, bearer, "2024-01-01T03:00:01Z"); - assertEquals(400, afterLatest.status()); - assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, afterLatest.errorCode()); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "The provided timestamp 1704078001000 ms (2024-01-01T03:00:01Z) is after the latest" + + " available version 3. Please use a timestamp less than or equal to 1704078000000" + + " ms (2024-01-01T03:00:00Z).", + afterLatest); Response invalid = version(orders, bearer, "not-a-timestamp"); - assertEquals(400, invalid.status()); - assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, invalid.errorCode()); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "startingTimestamp must be an ISO-8601 UTC timestamp", + invalid); // Missing tables and ungranted shares are both reported as missing. Response missing = @@ -59,28 +68,70 @@ void queriesAGrantedTableVersion() { } @Test - void rejectsTablesKernelCannotRead() { + void answersATableKernelCannotReadWithoutItsStoragePath() { createShare("unreadable-version"); addObject("unreadable-version", "TABLE", "main.lake.unwritten", "lake.unwritten"); addObject("unreadable-version", "TABLE", "main.lake.raw", "lake.raw"); addObject("unreadable-version", "TABLE", "main.lake.future", "lake.future"); + addObject("unreadable-version", "TABLE", "main.lake.gapped", "lake.gapped"); + addObject("unreadable-version", "TABLE", "main.lake.noncontiguous", "lake.noncontiguous"); + addObject("unreadable-version", "TABLE", "main.lake.invalidlog", "lake.invalidlog"); String bearer = createAndActivateRecipient("unreadable-version-partner"); grant("unreadable-version", "unreadable-version-partner"); String lake = PROTOCOL + "/shares/unreadable-version/schemas/lake/tables/"; - // A Delta table with no log is the catalog's inconsistency, not the recipient's mistake. + // A Delta table with no log is the source table's own state: the recipient is told to contact + // the data provider, and is given the table's name as the share gives it. Response unwritten = version(lake + "unwritten/version", bearer, null); - assertEquals(502, unwritten.status()); - assertEquals(ErrorCodes.CATALOG_ERROR, unwritten.errorCode()); - Response raw = version(lake + "raw/version", bearer, null); - assertEquals(400, raw.status()); - assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, raw.errorCode()); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "Unable to access table unreadable-version.lake.unwritten: something is wrong with the" + + " table. Please contact your data provider.", + unwritten); + + // A log Kernel rejects is reported in Kernel's words, and the provider is to be contacted. + Response gapped = version(lake + "gapped/version", bearer, null); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "Invalid table found at the table: Cannot compute snapshot. Missing delta file version 0." + + " Please contact your data provider.", + gapped); + Response noncontiguous = version(lake + "noncontiguous/version", bearer, null); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "Invalid table found at the table: Missing delta files: versions are not contiguous:" + + " ([0, 2]) Please contact your data provider.", + noncontiguous); + // Kernel only checks the in-commit timestamps of a log it must read commit by commit, so the + // ask is a timestamped version. The table's directory has a space in its name. + Response invalidLog = version(lake + "invalidlog/version", bearer, "2024-06-01T00:00:00Z"); + assertError( + 400, + ErrorCodes.BAD_REQUEST, + "Invalid table found at the table: This table has the feature inCommitTimestamp enabled" + + " which requires the presence of the CommitInfo action in every commit. However, the" + + " CommitInfo action is missing from commit version 0. Please contact your data" + + " provider.", + invalidLog); - // A reader feature Kernel does not know is reported without the table's storage path. + // A reader feature Kernel does not know is named, and the recipient is told whom to contact. A + // table without a format is not a Delta table. Response future = version(lake + "future/version", bearer, null); - assertEquals(400, future.status()); - assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, future.errorCode()); - assertFalse(future.body().toString().contains(tables.toString())); + assertError( + 400, + ErrorCodes.INVALID_PARAMETER_VALUE, + "Table features futurefeature are found in table. This server cannot read them. Please" + + " contact your data provider.", + future); + Response raw = version(lake + "raw/version", bearer, null); + assertError(400, ErrorCodes.INVALID_PARAMETER_VALUE, "the table is not a Delta table", raw); + + for (Response answer : List.of(unwritten, gapped, noncontiguous, invalidLog, future, raw)) { + assertNoStoragePath(answer); + } } private static Response version(String path, String bearer, String startingTimestamp) { diff --git a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java new file mode 100644 index 000000000..bb38c9f27 --- /dev/null +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java @@ -0,0 +1,149 @@ +package io.opensharing.protocol; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import io.opensharing.TestServer.Response; +import io.opensharing.http.ErrorCodes; +import java.util.List; +import org.junit.jupiter.api.Test; + +/** + * Every table endpoint answers a source table that cannot be read the same way: the table's own + * failures get the provider-contact answer in the share's names, and never the storage path. + */ +class ProtocolUnreadableTableTest extends LocalDeltaTableSupport { + + private static final String UNREADABLE = + "Unable to access table unreadable-unwritten.lake.unwritten: something is wrong with the" + + " table. Please contact your data provider."; + private static final String INVALID_LOG = + "Invalid table found at the table: This table has the feature inCommitTimestamp enabled" + + " which requires the presence of the CommitInfo action in every commit. However, the" + + " CommitInfo action is missing from commit version 0. Please contact your data" + + " provider."; + private static final String FUTURE = + "Table features futurefeature are found in table. This server cannot read them. Please" + + " contact your data provider."; + + @Test + void answersEveryEndpointForATableWithoutALog() { + String lake = shareWith("unwritten"); + String bearer = recipient("unwritten"); + + for (Response answer : + List.of( + server.get(lake + "unwritten/version?startingTimestamp=2024-01-01T00:00:00Z", bearer), + server.get(lake + "unwritten/metadata", bearer), + server.post(lake + "unwritten/query", bearer, "{}"), + server.post(lake + "unwritten/query", bearer, "{\"startingVersion\":0}"), + server.get(lake + "unwritten/changes?startingVersion=0", bearer))) { + assertError(400, ErrorCodes.BAD_REQUEST, UNREADABLE, answer); + assertNoStoragePath(answer); + } + } + + @Test + void namesTheFeaturesOfATableKernelCannotReadOnEveryEndpoint() { + String lake = shareWith("future"); + String bearer = recipient("future"); + + for (Response answer : + List.of( + server.get(lake + "future/metadata", bearer), + server.post(lake + "future/query", bearer, "{}"), + server.get(lake + "future/changes?startingVersion=0", bearer))) { + assertError(400, ErrorCodes.INVALID_PARAMETER_VALUE, FUTURE, answer); + assertNoStoragePath(answer); + } + } + + @Test + void namesTheVersionOfAnEarlierSnapshotKernelCannotRead() { + String lake = shareWith("futuresince"); + String bearer = recipient("futuresince"); + String atVersion0 = + "Table features futurefeature are found in table version: 0. This server cannot read" + + " them. Please contact your data provider."; + + // The latest version is readable; version 0 is not. + assertEquals(200, server.get(lake + "futuresince/metadata", bearer).status()); + for (Response answer : + List.of( + server.get(lake + "futuresince/metadata?version=0", bearer), + server.post(lake + "futuresince/query", bearer, "{\"version\":0}"), + server.get(lake + "futuresince/changes?startingVersion=0", bearer))) { + assertError(400, ErrorCodes.INVALID_PARAMETER_VALUE, atVersion0, answer); + assertNoStoragePath(answer); + } + } + + @Test + void rejectsAChangeRangeThatStopsRecordingBeforeAnyLineIsWritten() { + String lake = shareWith("cdfmid"); + String bearer = recipient("cdfmid"); + String changes = lake + "cdfmid/changes"; + String version2 = + "Unable to access change data feed for unreadable-cdfmid.lake.cdfmid. CDF is not enabled" + + " on the original delta table for version 2. Please contact your data provider."; + + // A commit that changes nothing is part of a range, and gives no file. + Response quiet = server.get(changes + "?startingVersion=0&endingVersion=1", bearer); + assertEquals(200, quiet.status(), quiet.text()); + assertEquals(2, quiet.text().strip().split("\n").length, quiet.text()); + // The range is read whole before the response begins, so a version that stops recording + // answers 403 however the range is bounded, and not a reset stream. + for (String bounds : + List.of( + "startingVersion=0", + "startingVersion=0&endingVersion=2", + "startingTimestamp=2000-01-01T00:00:00Z")) { + assertError( + 403, + ErrorCodes.PERMISSION_DENIED, + version2, + server.get(changes + "?" + bounds, bearer)); + } + // A timestamp after the latest commit is rejected too. + Response late = + server.get(changes + "?startingVersion=0&endingTimestamp=2100-01-01T00:00:00Z", bearer); + assertEquals(400, late.status(), late.text()); + assertEquals(ErrorCodes.INVALID_PARAMETER_VALUE, late.errorCode(), late.text()); + } + + @Test + void reportsAnInvalidLogInKernelsWordsWithoutThePathInEitherSpelling() { + String lake = shareWith("invalidlog"); + String bearer = recipient("invalidlog"); + + // Kernel reads the in-commit timestamps of a log only when asked for a version by timestamp. + for (Response answer : + List.of( + server.post( + lake + "invalidlog/query", bearer, "{\"timestamp\":\"2024-06-01T00:00:00Z\"}"), + server.post(lake + "invalidlog/query", bearer, "{\"version\":0}"), + server.get(lake + "invalidlog/metadata?timestamp=2024-06-01T00:00:00Z", bearer), + server.get(lake + "invalidlog/version?startingTimestamp=2024-06-01T00:00:00Z", bearer), + server.get(lake + "invalidlog/changes?startingTimestamp=2024-06-01T00:00:00Z", bearer), + server.get( + lake + "invalidlog/changes?startingVersion=0&endingTimestamp=2024-06-01T00:00:00Z", + bearer))) { + assertError(400, ErrorCodes.BAD_REQUEST, INVALID_LOG, answer); + assertNoStoragePath(answer); + } + } + + /** A share named for {@code table}, which holds only it, as {@code lake.
}. */ + private String shareWith(String table) { + String share = "unreadable-" + table; + createShare(share); + addObject(share, "TABLE", "main.lake." + table, "lake." + table); + return PROTOCOL + "/shares/" + share + "/schemas/lake/tables/"; + } + + /** The bearer token of a new recipient granted the share {@link #shareWith} made. */ + private String recipient(String table) { + String bearer = createAndActivateRecipient("unreadable-" + table + "-partner"); + grant("unreadable-" + table, "unreadable-" + table + "-partner"); + return bearer; + } +} diff --git a/server/opensharing-spark-e2e/src/test/java/io/opensharing/protocol/SparkSharedTableQueryIntegrationTest.java b/server/opensharing-spark-e2e/src/test/java/io/opensharing/protocol/SparkSharedTableQueryIntegrationTest.java index f64b3d178..fe8cd9d9a 100644 --- a/server/opensharing-spark-e2e/src/test/java/io/opensharing/protocol/SparkSharedTableQueryIntegrationTest.java +++ b/server/opensharing-spark-e2e/src/test/java/io/opensharing/protocol/SparkSharedTableQueryIntegrationTest.java @@ -231,8 +231,7 @@ void queriesAwsChangeDataFeed() { .load(table) .collectAsList()); assertTrue( - afterLatest.contains("startingTimestamp is after the latest table version timestamp"), - afterLatest); + afterLatest.contains("is after the latest available version"), afterLatest); } }