From 59226070880b93928c79d955f0c4e005df7242eb Mon Sep 17 00:00:00 2001 From: Sun Cao Date: Fri, 13 Nov 2026 01:22:11 +0000 Subject: [PATCH] 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); } }