From 59226070880b93928c79d955f0c4e005df7242eb Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Fri, 13 Nov 2026 01:22:11 +0000 Subject: [PATCH 1/5] Answer a missing or invalid shared-table Delta log with errors that name the data provider A shared table whose Delta log is missing, starts after version 0, has a gap, or is otherwise invalid, or whose version Kernel cannot read, returned 500 INTERNAL_ERROR or an error code and message of this server's own. The recipient cannot fix any of these, so the answer now says what is wrong and, when the shared table itself is at fault, whom to contact. DeltaKernel classifies every Kernel failure once, by Kernel's exception type rather than its message text: - A missing log (TableNotFoundException), or a file that is missing or denied (FileNotFoundException, AccessDeniedException), is the shared table's own state: 400 BAD_REQUEST "Unable to access table ..: something is wrong with the table. Please contact your data provider." The table is named as the share names it, and its storage path stays in the log. - An InvalidTableException, such as a gap in the log, is reported in Kernel's own words, with every spelling of the table's path and any other location removed, and the recipient is asked to contact the data provider: 400 BAD_REQUEST. - Any other Kernel report, such as a version or timestamp the table does not have, is the request's mistake in Kernel's words, without the path: 400 BAD_REQUEST. - A failure of the storage layer for a reason of its own stays a server error. - A reader feature or version Kernel cannot read is named in a fixed order: 400 INVALID_PARAMETER_VALUE "Table features are found in table[ version: ]. This server cannot read them. Please contact your data provider." The version endpoint no longer pre-checks a timestamp against the latest commit and leaves that to Kernel, and a snapshot is opened straight at the version or timestamp asked for. Adds ErrorCodes.BAD_REQUEST, ApiException.badRequest and ApiException.unsupportedFeatures, and fixtures for a log with in-commit timestamps but no CommitInfo (in a directory with a space in its name) and a table that is readable at its latest version but not at version 0. Co-authored-by: Isaac Signed-off-by: Sun Cao --- .../asset/table/ProtocolTables.java | 104 +++++++--- .../asset/table/delta/DeltaKernel.java | 158 ++++++++++++--- .../asset/table/delta/DeltaSnapshots.java | 46 ++--- .../table/delta/DeltaTableMetadataReader.java | 4 + .../table/delta/DeltaTableQueryReader.java | 20 +- .../table/delta/SourceTableException.java | 34 ++++ .../io/opensharing/http/ApiException.java | 24 +++ .../java/io/opensharing/http/ErrorCodes.java | 1 + .../table/delta/DeltaKernelErrorsTest.java | 189 ++++++++++++++++++ .../protocol/LocalDeltaTableSupport.java | 82 +++++++- .../protocol/ProtocolApiSupport.java | 8 + .../ProtocolTableMetadataIntegrationTest.java | 10 +- .../protocol/ProtocolTableMetadataTest.java | 36 +--- .../ProtocolTableQueryIntegrationTest.java | 14 +- .../protocol/ProtocolTableQueryTest.java | 6 +- .../ProtocolTableVersionIntegrationTest.java | 12 +- .../protocol/ProtocolTableVersionTest.java | 83 ++++++-- .../protocol/ProtocolUnreadableTableTest.java | 111 ++++++++++ .../SparkSharedTableQueryIntegrationTest.java | 3 +- 19 files changed, 787 insertions(+), 158 deletions(-) create mode 100644 server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/SourceTableException.java create mode 100644 server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaKernelErrorsTest.java create mode 100644 server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java 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..408d6fa01 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))); } /** @@ -144,7 +150,11 @@ public DeltaTableMetadataReader.Result metadata( ShareEntity share = protocolShares.requireGranted(recipient, shareName); 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)); } /** @@ -207,7 +217,11 @@ public void query( 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 +237,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))); } /** @@ -254,17 +274,49 @@ public void changes( 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()))); + } + + /** + * 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. */ 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..895e485dc 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,16 @@ import io.opensharing.catalog.TableProperties; import io.opensharing.exception.CatalogException; import io.opensharing.http.ApiException; +import java.io.FileNotFoundException; +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 +40,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 +63,134 @@ 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 || storageUnavailable(failed)) { + log.warn("Delta table at '{}' is unavailable: {}", tablePath, failed.toString()); + 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, 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; + forms.addAll(List.of(base, base.replace(" ", "%20"), base.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..cebe2f392 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; @@ -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..6610c4d90 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; @@ -181,6 +182,8 @@ public void read( table.catalogAssetId(), snapshot.getVersion(), Instant.now().plus(URL_TTL)) : null); } + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); } } @@ -215,6 +218,8 @@ public void readChanges( includeHistoricalProtocol), options, sink); + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); } } @@ -274,6 +279,8 @@ public void readChangeDataFeed( start, resolvedEnd, includeHistoricalMetadata, includeHistoricalProtocol), options, sink); + } catch (KernelException | KernelEngineException failed) { + throw DeltaKernel.classifyRead(failed, table); } } @@ -281,9 +288,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); } } @@ -307,12 +313,8 @@ private void changes( 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); } // The protocol reports the starting version as the table version of a change response. 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..067c9cebc --- /dev/null +++ b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/SourceTableException.java @@ -0,0 +1,34 @@ +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 SourceTableException(String logMessage) { + super(logMessage); + } + + /** 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); + } + + /** The recipient's answer, naming the table {@code sharedName}, as {@code share.schema.table}. */ + public ApiException forRecipient(String sharedName) { + 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/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..bde309a4b --- /dev/null +++ b/server/opensharing-server-core/src/test/java/io/opensharing/asset/table/delta/DeltaKernelErrorsTest.java @@ -0,0 +1,189 @@ +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 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/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java index a2d27a2a9..42d544b38 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,12 @@ * {@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. */ abstract class LocalDeltaTableSupport extends ProtocolApiSupport { @@ -39,6 +47,18 @@ 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\"}"); + + /** 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; @@ -51,6 +71,24 @@ static void startLocalDeltaServer() { write( "future/_delta_log/%020d.json".formatted(0), FUTURE_PROTOCOL_ACTION + METADATA_ACTION.formatted("future")); + 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 +139,26 @@ 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 """ .formatted( orders, @@ -109,17 +167,35 @@ static void startLocalDeltaServer() { events, location("unwritten"), location("raw"), - location("future")); + location("future"), + location("gapped"), + location("noncontiguous"), + unescapedLocation(INVALID_LOG_DIRECTORY), + location("futuresince")); 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/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..53167159e 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,7 +79,11 @@ void queriesGrantedTableMetadata() { assertEquals(200, atTimestamp.status()); assertEquals("1", atTimestamp.headers().get("Delta-Table-Version")); - assertInvalid(metadata(orders + "?version=9", 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 + "?version=1×tamp=2024-01-01T01:30:00Z", bearer, null)); assertInvalid(metadata(orders + "?timestamp=not-a-timestamp", bearer, null)); @@ -93,36 +97,6 @@ void queriesGrantedTableMetadata() { assertEquals(ErrorCodes.RESOURCE_DOES_NOT_EXIST, hidden.errorCode()); } - @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())); - } - private static Response metadata(String path, String bearer, String capabilities) { return capabilities == null ? server.get(path, bearer) 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..685bedb1c 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,7 +77,11 @@ void queriesGrantedTable() { assertEquals(200, atTimestamp.status()); assertEquals("0", atTimestamp.headers().get("Delta-Table-Version")); - assertInvalid(query(events, bearer, "{\"version\":9}", 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)); String both = "{\"version\":1,\"timestamp\":\"2024-01-01T00:30:00Z\"}"; assertInvalid(query(events, bearer, both, null, null)); assertInvalid(query(events, bearer, "{\"timestamp\":\"not-a-timestamp\"}", null, null)); 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..d55a45949 --- /dev/null +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java @@ -0,0 +1,111 @@ +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/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 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))) { + 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); } } From 0c9e105fbc66c1ee26eb0f7adf5329d5990a4ed8 Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Fri, 13 Nov 2026 01:46:08 +0000 Subject: [PATCH 2/5] Answer version, range and change-data mistakes with specific errors A request with a version or timestamp the table does not have, a malformed or contradictory range, or a Change Data Feed the source table does not record got errors of this server's own wording, and some leaked the table's storage path. Each now has one specific answer: - A non-numeric version, startingVersion or endingVersion is 400 INVALID_PARAMETER_VALUE " is not a valid number.", and a negative one " cannot be negative." - More than one of version, timestamp and startingVersion, or more than one starting or ending bound of a Change Data Feed, names the parameters to choose from. A reversed range names both versions. - A Change Data Feed start or end after the table's latest version, or an end timestamp after its latest commit, is rejected with the latest version or commit time to use, rather than capped. - A table that did not record change data for a version in the range is the source table's own state: 403 PERMISSION_DENIED "Unable to access change data feed for ..
. CDF is not enabled on the original delta table for version . Please contact your data provider." - A version or timestamp Kernel rejects keeps Kernel's own message, in 400 BAD_REQUEST, without the table's storage path. A Change Data Feed range is read whole for its protocols and metaData before the response begins, so a version that stops recording change data, or needs reader features the client did not advertise, answers with its status instead of resetting a stream that has begun. The checks and their messages live in TableRequestChecks, and run once, in ProtocolTables, before the table is read. The snapshot and metadata readers no longer check for a version together with a timestamp. Stacked on the change that classifies Kernel's failures. Co-authored-by: Isaac Signed-off-by: Sun Cao --- .../asset/table/ProtocolTables.java | 44 +++-- .../asset/table/TableRequestChecks.java | 111 +++++++++++++ .../table/delta/DeltaTableMetadataReader.java | 4 - .../table/delta/DeltaTableQueryReader.java | 151 +++++++++++------- .../table/delta/SourceTableException.java | 22 ++- .../protocol/DeltaSharingProtocolService.java | 13 +- .../delta/DeltaTableQueryReaderTest.java | 43 ++++- .../protocol/LocalDeltaTableSupport.java | 27 +++- .../ProtocolTableChangesIntegrationTest.java | 31 ++-- .../protocol/ProtocolTableChangesTest.java | 113 +++++++++++-- .../protocol/ProtocolTableMetadataTest.java | 36 ++++- .../protocol/ProtocolTableQueryTest.java | 65 +++++++- .../protocol/ProtocolUnreadableTableTest.java | 40 ++++- 13 files changed, 581 insertions(+), 119 deletions(-) create mode 100644 server/opensharing-server-core/src/main/java/io/opensharing/asset/table/TableRequestChecks.java 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 408d6fa01..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 @@ -148,6 +148,8 @@ 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 readingTable( @@ -212,10 +214,11 @@ 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) { readingTable( share, @@ -271,6 +274,7 @@ 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); @@ -294,6 +298,33 @@ public void changes( 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. @@ -345,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/DeltaTableMetadataReader.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableMetadataReader.java index cebe2f392..d8d76ec3a 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 @@ -10,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; /** @@ -31,9 +30,6 @@ 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; 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 6610c4d90..e78460318 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 @@ -40,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; @@ -82,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) @@ -128,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. @@ -204,9 +206,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, @@ -224,11 +226,11 @@ public void readChanges( } /** - * 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, @@ -244,32 +246,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, @@ -284,6 +284,25 @@ public void readChangeDataFeed( } } + /** + * 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); + } + } + private static long versionBeforeOrAt( TableImpl table, DeltaKernel.Session session, Instant endingTimestamp) { try { @@ -317,6 +336,14 @@ private void changes( 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. out.begin(range.start()); // With includeHistoricalProtocol, a starting protocol carries its version like later ones. A @@ -333,10 +360,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) { @@ -349,19 +376,47 @@ private void changes( } } + /** + * Checks the reader features 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())) { + out.requireReaderFeatures(Protocol.fromRow(row.getStruct(columns.protocol()))); + } else if (!row.isNullAt(columns.metadata()) + && range.changeDataFeed() + && !changeDataFeedEnabled(Metadata.fromRow(row.getStruct(columns.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()); @@ -378,19 +433,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()) { @@ -407,17 +457,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) { @@ -437,13 +476,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()) { @@ -776,7 +808,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 index 067c9cebc..8806612e4 100644 --- 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 @@ -14,17 +14,35 @@ public final class SourceTableException extends RuntimeException { private static final String CONTACT_PROVIDER = "Please contact your data provider."; - private SourceTableException(String logMessage) { + 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); + 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 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/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 42d544b38..469657f22 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 @@ -27,7 +27,9 @@ * 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. + * reader feature Kernel does not know at version 0 but not at its latest. {@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 { @@ -71,6 +73,21 @@ static void startLocalDeltaServer() { write( "future/_delta_log/%020d.json".formatted(0), FUTURE_PROTOCOL_ACTION + METADATA_ACTION.formatted("future")); + // 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( @@ -159,6 +176,11 @@ static void startLocalDeltaServer() { subtype: MANAGED storageLocation: %s format: delta + - identifier: main.lake.cdfmid + attributes: + subtype: MANAGED + storageLocation: %s + format: delta """ .formatted( orders, @@ -171,7 +193,8 @@ static void startLocalDeltaServer() { location("gapped"), location("noncontiguous"), unescapedLocation(INVALID_LOG_DIRECTORY), - location("futuresince")); + location("futuresince"), + location("cdfmid")); Properties properties = new Properties(); properties.setProperty("catalog.local.file", write("local-catalog.yml", catalog).toString()); restartServer(properties); 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/ProtocolTableMetadataTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTableMetadataTest.java index 53167159e..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 @@ -84,7 +84,6 @@ void queriesGrantedTableMetadata() { 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 + "?version=1×tamp=2024-01-01T01:30:00Z", bearer, null)); assertInvalid(metadata(orders + "?timestamp=not-a-timestamp", bearer, null)); // A table in an ungranted share is 404, not 403. @@ -97,6 +96,41 @@ void queriesGrantedTableMetadata() { assertEquals(ErrorCodes.RESOURCE_DOES_NOT_EXIST, hidden.errorCode()); } + @Test + 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) { return capabilities == null ? server.get(path, bearer) 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 685bedb1c..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 @@ -82,8 +82,6 @@ void queriesGrantedTable() { 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)); - String both = "{\"version\":1,\"timestamp\":\"2024-01-01T00:30:00Z\"}"; - assertInvalid(query(events, bearer, both, null, null)); assertInvalid(query(events, bearer, "{\"timestamp\":\"not-a-timestamp\"}", null, null)); // A table in an ungranted share is 404, not 403. @@ -98,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/ProtocolUnreadableTableTest.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java index d55a45949..bb38c9f27 100644 --- a/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java +++ b/server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolUnreadableTableTest.java @@ -32,6 +32,7 @@ void answersEveryEndpointForATableWithoutALog() { 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}"), @@ -76,6 +77,39 @@ void namesTheVersionOfAnEarlierSnapshotKernelCannotRead() { } } + @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"); @@ -87,8 +121,12 @@ void reportsAnInvalidLogInKernelsWordsWithoutThePathInEitherSpelling() { 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/metadata?timestamp=2024-06-01T00:00:00Z", bearer))) { + lake + "invalidlog/changes?startingVersion=0&endingTimestamp=2024-06-01T00:00:00Z", + bearer))) { assertError(400, ErrorCodes.BAD_REQUEST, INVALID_LOG, answer); assertNoStoragePath(answer); } From 519ffbdc6cd71b8b0c946293664dad5c573a0414 Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Fri, 13 Nov 2026 01:57:13 +0000 Subject: [PATCH 3/5] Refuse tables whose Delta properties the client did not advertise A table whose Delta properties enable a reader feature that the recipient's client did not advertise cannot be served to that client: column mapping by name (delta.columnMapping.mode) and deletion vectors (delta.enableDeletionVectors) are only readable by a client that declares them in delta-sharing-capabilities. Such a request now answers 400 INVALID_PARAMETER_VALUE "Table features are found in table version: . Query with responseFormat=delta and advertise the features in delta-sharing-capabilities, or ask your data provider to disable them." on every snapshot the server serves: the metadata, query and change answers, for the latest and for a historical version, and for the metadata of each commit of a change feed, before the response is written; a change feed's commits are read whole first. A property set to its off value never blocks a request, and a property no feature depends on is ignored. The same answer, with the same wording, now reports reader features the client did not advertise, naming every one of them in a fixed order with the table version, where it named the first. Deletion vectors stay in a protocol after they are turned off, so only their property decides. The advertised reader features are parsed once per request, and DeltaSharingCapabilities keeps its properties in an ordered list. Adds column-mapping, deletion-vector, properties-off and later-column- mapping tables to the local fixtures. Stacked on the change that answers version, range and change-data mistakes. Co-authored-by: Isaac Signed-off-by: Sun Cao --- .../asset/table/DeltaSharingCapabilities.java | 110 ++++++++--- .../table/delta/DeltaTableMetadataReader.java | 4 + .../table/delta/DeltaTableQueryReader.java | 38 ++-- .../table/DeltaSharingCapabilitiesTest.java | 146 +++++++++++---- .../protocol/LocalDeltaTableSupport.java | 76 +++++++- .../protocol/ProtocolTablePropertiesTest.java | 177 ++++++++++++++++++ 6 files changed, 468 insertions(+), 83 deletions(-) create mode 100644 server/opensharing-server/src/test/java/io/opensharing/protocol/ProtocolTablePropertiesTest.java 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..c618e4790 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. 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().equals(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/delta/DeltaTableMetadataReader.java b/server/opensharing-server-core/src/main/java/io/opensharing/asset/table/delta/DeltaTableMetadataReader.java index d8d76ec3a..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 @@ -33,6 +33,10 @@ public Result read( 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()); 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 e78460318..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 @@ -144,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()); @@ -325,7 +326,8 @@ 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 { @@ -377,8 +379,8 @@ private void changes( } /** - * Checks the reader features and, for a Change Data Feed, the change data recording of each - * protocol and metaData in the commits of {@code range}. + * 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) @@ -391,11 +393,14 @@ private static void checkCommits( PROTOCOL_AND_METADATA_SCHEMA, (row, columns) -> { if (!row.isNullAt(columns.protocol())) { - out.requireReaderFeatures(Protocol.fromRow(row.getStruct(columns.protocol()))); - } else if (!row.isNullAt(columns.metadata()) - && range.changeDataFeed() - && !changeDataFeedEnabled(Metadata.fromRow(row.getStruct(columns.metadata())))) { - throw SourceTableException.changeDataNotRecorded(version); + 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); + } } }); } @@ -522,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; @@ -537,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; @@ -544,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. */ 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..acfd04ea5 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,130 @@ 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)); 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.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/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java b/server/opensharing-server/src/test/java/io/opensharing/protocol/LocalDeltaTableSupport.java index 469657f22..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 @@ -27,9 +27,11 @@ * 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.cdfmid} records change data at version 0, commits no change at version 1, and stops - * recording at version 2. + * 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 { @@ -59,11 +61,30 @@ abstract class LocalDeltaTableSupport extends ProtocolApiSupport { + "\"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); @@ -73,6 +94,31 @@ 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( @@ -176,6 +222,26 @@ static void startLocalDeltaServer() { 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 @@ -194,6 +260,10 @@ static void startLocalDeltaServer() { 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()); 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); + } +} From 450d48f8940a285802d0cfb1144a43c190d0c733 Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Fri, 13 Nov 2026 02:28:31 +0000 Subject: [PATCH 4/5] Read the off values of feature properties in any case Delta reads delta.columnMapping.mode and delta.enableDeletionVectors without regard to case, so "NONE" and "False" turn their features off. The check no longer refuses a table that sets them so. Co-authored-by: Isaac Signed-off-by: Sun Cao --- .../asset/table/DeltaSharingCapabilities.java | 6 +++--- .../asset/table/DeltaSharingCapabilitiesTest.java | 9 +++++++++ 2 files changed, 12 insertions(+), 3 deletions(-) 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 c618e4790..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 @@ -88,8 +88,8 @@ public static Declared declared(String header) { /** * 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. This - * covers the table's version {@code version}. + * 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) { @@ -101,7 +101,7 @@ public static void requireSupportedProperties( String value = configuration.get(checked.property()); if (value != null && !declared.readerFeatures().contains(checked.feature()) - && !checked.offValue().equals(value.trim())) { + && !checked.offValue().equalsIgnoreCase(value.trim())) { unsupported.add(checked.property()); } } 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 acfd04ea5..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 @@ -182,6 +182,15 @@ void aTablePropertyThatEnablesAFeatureNeedsTheFeatureAdvertised() { "delta.columnMapping.mode", "none", "delta.appendOnly", "true"), 3)); + // Delta reads the off values in any case. + assertDoesNotThrow( + () -> + DeltaSharingCapabilities.requireSupportedProperties( + DeltaSharingCapabilities.declared("responseformat=delta"), + Map.of( + "delta.enableDeletionVectors", "False", + "delta.columnMapping.mode", "NONE"), + 3)); assertDoesNotThrow( () -> DeltaSharingCapabilities.requireSupportedProperties( From 79e2163de67196284898071548c57efb566cbc96 Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Fri, 13 Nov 2026 02:34:20 +0000 Subject: [PATCH 5/5] Log denied table files as errors and strip every storage scheme's path A denied read of the table's files can be this server's own expired or misconfigured credential, so it is logged at error level for operators, while the recipient is still told to contact the data provider. The table path is also removed when Kernel's message spells it fully percent-encoded, and tests cover s3, s3a, abfss, gs and file locations in each spelling. Co-authored-by: Isaac Signed-off-by: Sun Cao --- .../asset/table/delta/DeltaKernel.java | 25 ++++++++++++++--- .../table/delta/DeltaKernelErrorsTest.java | 28 +++++++++++++++++++ 2 files changed, 49 insertions(+), 4 deletions(-) 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 895e485dc..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 @@ -23,6 +23,8 @@ 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; @@ -104,8 +106,14 @@ static RuntimeException classifyRead(RuntimeException failed, ResolvedAsset tabl * @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 || storageUnavailable(failed)) { - log.warn("Delta table at '{}' is unavailable: {}", tablePath, failed.toString()); + 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) { @@ -175,7 +183,8 @@ static ApiException kernelError(RuntimeException failed, String tablePath, Strin /** * 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, since a path and its URI form differ in all of those. Longer spellings come + * 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) { @@ -187,7 +196,15 @@ private static List pathForms(String tablePath) { Set forms = new HashSet<>(); for (String path : paths) { String base = path.endsWith("/") ? path.substring(0, path.length() - 1) : path; - forms.addAll(List.of(base, base.replace(" ", "%20"), base.replace("%20", " "))); + 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(); 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 index bde309a4b..2a2c6577d 100644 --- 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 @@ -134,6 +134,34 @@ void stripsOtherLocationsWithASchemeFromKernelWords() { .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 =