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); } }