You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iceberg.apache.org by ze...@apache.org on 2026/07/14 15:58:30 UTC
(iceberg-go) branch main updated: feat(rest): implement scan planning client methods (#1324)
This is an automated email from the ASF dual-hosted git repository.
zeroshade pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iceberg-go.git
The following commit(s) were added to refs/heads/main by this push:
new ee3687ce feat(rest): implement scan planning client methods (#1324)
ee3687ce is described below
commit ee3687ced24d194c566579fd3dcc8a574dadb4ac
Author: Revanth <re...@gmail.com>
AuthorDate: Tue Jul 14 10:58:24 2026 -0500
feat(rest): implement scan planning client methods (#1324)
---
catalog/rest/endpoints.go | 5 +
catalog/rest/rest.go | 194 ++++++++--
catalog/rest/rest_internal_test.go | 172 ++++++++-
catalog/rest/scan_planning.go | 405 +++++++++++++++++++--
catalog/rest/scan_planning_test.go | 707 +++++++++++++++++++++++++++++++++++++
5 files changed, 1419 insertions(+), 64 deletions(-)
diff --git a/catalog/rest/endpoints.go b/catalog/rest/endpoints.go
index 7cc2dcf2..a4e86811 100644
--- a/catalog/rest/endpoints.go
+++ b/catalog/rest/endpoints.go
@@ -105,6 +105,10 @@ var (
endpointRegisterTable = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/register"}
endpointReportMetrics = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/metrics"}
endpointTableCredentials = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/credentials"}
+ endpointPlanTableScan = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/plan"}
+ endpointFetchPlanResult = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}"}
+ endpointCancelPlanning = endpoint{http.MethodDelete, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/plan/{plan-id}"}
+ endpointFetchScanTasks = endpoint{http.MethodPost, "/v1/{prefix}/namespaces/{namespace}/tables/{table}/tasks"}
endpointListViews = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/views"}
endpointLoadView = endpoint{http.MethodGet, "/v1/{prefix}/namespaces/{namespace}/views/{view}"}
@@ -148,6 +152,7 @@ var allEndpoints = []endpoint{
endpointListTables, endpointLoadTable, endpointTableExists, endpointCreateTable,
endpointUpdateTable, endpointDeleteTable, endpointRenameTable, endpointRegisterTable,
endpointReportMetrics, endpointTableCredentials,
+ endpointPlanTableScan, endpointFetchPlanResult, endpointCancelPlanning, endpointFetchScanTasks,
endpointListViews, endpointLoadView, endpointViewExists, endpointCreateView,
endpointUpdateView, endpointDeleteView, endpointRenameView, endpointRegisterView,
endpointListFunctions, endpointLoadFunction,
diff --git a/catalog/rest/rest.go b/catalog/rest/rest.go
index 8e8fbda5..1a66fa3d 100644
--- a/catalog/rest/rest.go
+++ b/catalog/rest/rest.go
@@ -73,6 +73,12 @@ const (
bearerPrefix = "Bearer"
keyPrefix = "prefix"
+ // headerIcebergAccessDelegation requests server-side storage-credential
+ // vending. It is a session default (defaultAccessDelegation) and a
+ // per-request header on the scan-planning endpoints that vend credentials.
+ headerIcebergAccessDelegation = "X-Iceberg-Access-Delegation"
+ defaultAccessDelegation = "vended-credentials"
+
keyNamespaceSeparator = "namespace-separator"
defaultNamespaceSeparator = "%1F"
@@ -228,10 +234,17 @@ type sessionTransport struct {
const emptyStringHash = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
func (s *sessionTransport) RoundTrip(r *http.Request) (*http.Response, error) {
+ // A session default is applied unless the request already carries that
+ // header (a per-request override of any default, not just Content-Type
+ // wins) or explicitly opted out of it via withSuppressedHeaders (carried on
+ // the context as an explicit set, never inferred from header values).
+ suppressed := suppressedHeadersFrom(r.Context())
for k, v := range s.defaultHeaders {
- // Skip Content-Type if it's already set in the request
- // to avoid duplicate headers (e.g., when using PostForm)
- if http.CanonicalHeaderKey(k) == "Content-Type" && r.Header.Get("Content-Type") != "" {
+ ck := http.CanonicalHeaderKey(k)
+ if _, ok := r.Header[ck]; ok {
+ continue
+ }
+ if _, ok := suppressed[ck]; ok {
continue
}
for _, hdr := range v {
@@ -239,6 +252,12 @@ func (s *sessionTransport) RoundTrip(r *http.Request) (*http.Response, error) {
}
}
+ // Ordering is load-bearing: authManager runs after the default-header loop
+ // and Set-overwrites, so the managed auth header always wins even though the
+ // loop above lets an arbitrary per-request header (withHeaders) override a
+ // session default of the same key. A caller cannot suppress or spoof the
+ // Authorization header by supplying its own. Do not reorder this before the
+ // default-header loop.
if s.authManager != nil && r.Context().Value(skipOAuth) == nil {
k, v, err := s.authManager.AuthHeader()
if err != nil {
@@ -293,16 +312,117 @@ func (s *sessionTransport) RoundTrip(r *http.Request) (*http.Response, error) {
return s.RoundTripper.RoundTrip(r)
}
-func do[T any](ctx context.Context, method string, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, allowNoContent bool) (ret T, err error) {
+// suppressHeadersKey carries the set of session-default header keys (canonical
+// form) that a request opted out of, so sessionTransport.RoundTrip can consult
+// an explicit set rather than inferring suppression from header values.
+type suppressHeadersKey struct{}
+
+// reqConfig holds the optional per-request knobs shared by do and doPost:
+// headers to set, session-default headers to suppress, a body error.type ->
+// error override, and whether an HTTP 204 is a valid empty result.
+type reqConfig struct {
+ headers map[string]string
+ suppressHeaders []string
+ errorTypeOverride map[string]error
+ allowNoContent bool
+ requireBody bool
+}
+
+type reqOption func(*reqConfig)
+
+// withHeaders sets per-request headers, merging with any already set so options
+// compose. A per-request header takes precedence over a session default because
+// sessionTransport.RoundTrip skips any default whose key is already present.
+func withHeaders(headers map[string]string) reqOption {
+ return func(c *reqConfig) {
+ if c.headers == nil {
+ c.headers = make(map[string]string, len(headers))
+ }
+ maps.Copy(c.headers, headers)
+ }
+}
+
+// withSuppressedHeaders prevents the named session-default headers from being
+// sent on this request. Names accumulate so options compose. Suppression is
+// carried through the request context (see RoundTrip), not encoded as a header
+// value, so req.Header only ever means "headers to send".
+func withSuppressedHeaders(names ...string) reqOption {
+ return func(c *reqConfig) { c.suppressHeaders = append(c.suppressHeaders, names...) }
+}
+
+// withErrorTypeOverride maps a non-200 response to a specific error by the REST
+// error.type in the response body. It takes precedence over the status-code
+// override so a shared status (e.g. a 404 that can be a missing plan, table, or
+// namespace) can split into distinct sentinels. Entries accumulate so options
+// compose; an unset or unmatched error.type falls through to the status-code
+// override.
+func withErrorTypeOverride(byType map[string]error) reqOption {
+ return func(c *reqConfig) {
+ if c.errorTypeOverride == nil {
+ c.errorTypeOverride = make(map[string]error, len(byType))
+ }
+ maps.Copy(c.errorTypeOverride, byType)
+ }
+}
+
+// allowNoContent treats an HTTP 204 No Content response as a valid empty result
+// rather than trying to decode a body.
+func allowNoContent() reqOption {
+ return func(c *reqConfig) { c.allowNoContent = true }
+}
+
+// requireBody rejects an HTTP 200 with an empty body rather than decoding it to
+// the zero result. Use it when a 200 must carry a payload, so a truncated or
+// proxy-stripped response cannot masquerade as a successful empty result (e.g.
+// fetchScanTasks returning "zero tasks" and silently dropping work).
+func requireBody() reqOption {
+ return func(c *reqConfig) { c.requireBody = true }
+}
+
+func newReqConfig(opts []reqOption) reqConfig {
+ var cfg reqConfig
+ for _, opt := range opts {
+ opt(&cfg)
+ }
+
+ return cfg
+}
+
+// withSuppressedHeadersCtx returns ctx carrying the canonicalized suppression
+// set, or ctx unchanged when nothing is suppressed.
+func withSuppressedHeadersCtx(ctx context.Context, names []string) context.Context {
+ if len(names) == 0 {
+ return ctx
+ }
+
+ set := make(map[string]struct{}, len(names))
+ for _, n := range names {
+ set[http.CanonicalHeaderKey(n)] = struct{}{}
+ }
+
+ return context.WithValue(ctx, suppressHeadersKey{}, set)
+}
+
+func suppressedHeadersFrom(ctx context.Context) map[string]struct{} {
+ set, _ := ctx.Value(suppressHeadersKey{}).(map[string]struct{})
+
+ return set
+}
+
+func do[T any](ctx context.Context, method string, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, opts ...reqOption) (ret T, err error) {
+ cfg := newReqConfig(opts)
+
var (
req *http.Request
rsp *http.Response
)
uri := baseURI.JoinPath(path...).String()
+ ctx = withSuppressedHeadersCtx(ctx, cfg.suppressHeaders)
if req, err = http.NewRequestWithContext(ctx, method, uri, nil); err != nil {
return ret, err
}
+ setRequestHeaders(req, cfg.headers)
if rsp, err = cl.Do(req); err != nil {
return ret, err
@@ -312,12 +432,12 @@ func do[T any](ctx context.Context, method string, baseURI *url.URL, path []stri
_ = rsp.Body.Close()
}()
- if allowNoContent && rsp.StatusCode == http.StatusNoContent {
+ if cfg.allowNoContent && rsp.StatusCode == http.StatusNoContent {
return ret, err
}
if rsp.StatusCode != http.StatusOK {
- return ret, handleNon200(rsp, override)
+ return ret, handleNon200(rsp, override, cfg.errorTypeOverride)
}
if method == http.MethodHead || method == http.MethodDelete {
@@ -331,25 +451,23 @@ func do[T any](ctx context.Context, method string, baseURI *url.URL, path []stri
return ret, err
}
-func doGet[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error) (ret T, err error) {
- return do[T](ctx, http.MethodGet, baseURI, path, cl, override, false)
+func doGet[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, opts ...reqOption) (ret T, err error) {
+ return do[T](ctx, http.MethodGet, baseURI, path, cl, override, opts...)
}
-func doDelete[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error) (ret T, err error) {
- return do[T](ctx, http.MethodDelete, baseURI, path, cl, override, true)
+func doDelete[T any](ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error, opts ...reqOption) (ret T, err error) {
+ return do[T](ctx, http.MethodDelete, baseURI, path, cl, override, append([]reqOption{allowNoContent()}, opts...)...)
}
func doHead(ctx context.Context, baseURI *url.URL, path []string, cl *http.Client, override map[int]error) error {
- _, err := do[struct{}](ctx, http.MethodHead, baseURI, path, cl, override, true)
+ _, err := do[struct{}](ctx, http.MethodHead, baseURI, path, cl, override, allowNoContent())
return err
}
-func doPost[Payload, Result any](ctx context.Context, baseURI *url.URL, path []string, payload Payload, cl *http.Client, override map[int]error) (ret Result, err error) {
- return doPostAllowNoContent[Payload, Result](ctx, baseURI, path, payload, cl, override, false)
-}
+func doPost[Payload, Result any](ctx context.Context, baseURI *url.URL, path []string, payload Payload, cl *http.Client, override map[int]error, opts ...reqOption) (ret Result, err error) {
+ cfg := newReqConfig(opts)
-func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url.URL, path []string, payload Payload, cl *http.Client, override map[int]error, allowNoContent bool) (ret Result, err error) {
var (
req *http.Request
rsp *http.Response
@@ -362,10 +480,12 @@ func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url
return ret, err
}
+ ctx = withSuppressedHeadersCtx(ctx, cfg.suppressHeaders)
req, err = http.NewRequestWithContext(ctx, http.MethodPost, uri, bytes.NewReader(data))
if err != nil {
return ret, err
}
+ setRequestHeaders(req, cfg.headers)
rsp, err = cl.Do(req)
if err != nil {
@@ -376,15 +496,19 @@ func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url
_ = rsp.Body.Close()
}()
- if allowNoContent && rsp.StatusCode == http.StatusNoContent {
+ if cfg.allowNoContent && rsp.StatusCode == http.StatusNoContent {
return ret, err
}
if rsp.StatusCode != http.StatusOK {
- return ret, handleNon200(rsp, override)
+ return ret, handleNon200(rsp, override, cfg.errorTypeOverride)
}
if rsp.ContentLength == 0 {
+ if cfg.requireBody {
+ return ret, fmt.Errorf("%w: empty response body on %s %s", ErrRESTError, req.Method, req.URL.Path)
+ }
+
return ret, err
}
@@ -395,7 +519,13 @@ func doPostAllowNoContent[Payload, Result any](ctx context.Context, baseURI *url
return ret, err
}
-func handleNon200(rsp *http.Response, override map[int]error) error {
+func setRequestHeaders(req *http.Request, headers map[string]string) {
+ for k, v := range headers {
+ req.Header.Set(k, v)
+ }
+}
+
+func handleNon200(rsp *http.Response, override map[int]error, typeOverride map[string]error) error {
var e errorResponse
// Only try to decode if there's a body (HEAD requests don't have one)
@@ -420,9 +550,23 @@ func handleNon200(rsp *http.Response, override map[int]error) error {
}
}
+ // The status-code override maps a status to a sentinel; a body error.type
+ // override refines it further (e.g. splitting a 404 into missing-plan vs.
+ // table vs. namespace). The type refinement only applies to a status the
+ // caller already mapped, because these error.type values are defined for
+ // specific statuses (404) in the REST spec: a 503 body carrying, say,
+ // NoSuchPlanIdException must still resolve to ErrServiceUnavailable rather
+ // than a 404 sentinel.
if override != nil {
- if err, ok := override[rsp.StatusCode]; ok {
- e.wrapping = err
+ if statusErr, ok := override[rsp.StatusCode]; ok {
+ if typeOverride != nil && e.Type != "" {
+ if typeErr, ok := typeOverride[e.Type]; ok {
+ e.wrapping = typeErr
+
+ return e
+ }
+ }
+ e.wrapping = statusErr
return e
}
@@ -768,7 +912,7 @@ func (r *Catalog) createSession(ctx context.Context, opts *options) (*http.Clien
session.defaultHeaders.Set("X-Client-Version", icebergRestSpecVersion)
session.defaultHeaders.Set("Content-Type", "application/json")
session.defaultHeaders.Set("User-Agent", "GoIceberg/"+iceberg.Version())
- session.defaultHeaders.Set("X-Iceberg-Access-Delegation", "vended-credentials")
+ session.defaultHeaders.Set(headerIcebergAccessDelegation, defaultAccessDelegation)
for k, v := range opts.headers {
session.defaultHeaders.Set(k, v)
@@ -1259,7 +1403,7 @@ func (r *Catalog) CommitTransaction(ctx context.Context, commits []table.TableCo
return err
}
- _, err = doPostAllowNoContent[payload, struct{}](
+ _, err = doPost[payload, struct{}](
ctx, r.baseURI, path,
payload{TableChanges: changes}, r.cl,
map[int]error{
@@ -1270,7 +1414,7 @@ func (r *Catalog) CommitTransaction(ctx context.Context, commits []table.TableCo
http.StatusServiceUnavailable: ErrCommitStateUnknown,
http.StatusGatewayTimeout: ErrCommitStateUnknown,
},
- true,
+ allowNoContent(),
)
return err
@@ -1468,8 +1612,8 @@ func (r *Catalog) RenameTable(ctx context.Context, from, to table.Identifier) (*
return nil, err
}
- _, err = doPostAllowNoContent[payload, any](ctx, r.baseURI, path, payload{Source: src, Destination: dst}, r.cl,
- map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}, true)
+ _, err = doPost[payload, any](ctx, r.baseURI, path, payload{Source: src, Destination: dst}, r.cl,
+ map[int]error{http.StatusNotFound: catalog.ErrNoSuchTable}, allowNoContent())
if err != nil {
return nil, err
}
diff --git a/catalog/rest/rest_internal_test.go b/catalog/rest/rest_internal_test.go
index 24782cb4..18992eec 100644
--- a/catalog/rest/rest_internal_test.go
+++ b/catalog/rest/rest_internal_test.go
@@ -913,6 +913,111 @@ func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
return f(r)
}
+func TestRoundTripDefaultHeaderHandling(t *testing.T) {
+ t.Parallel()
+
+ newSession := func(captured *http.Header) *sessionTransport {
+ s := &sessionTransport{
+ RoundTripper: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+ *captured = r.Header.Clone()
+
+ return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+ }),
+ defaultHeaders: http.Header{},
+ }
+ s.defaultHeaders.Set(headerIcebergAccessDelegation, defaultAccessDelegation)
+
+ return s
+ }
+
+ t.Run("applies default when absent", func(t *testing.T) {
+ t.Parallel()
+
+ var got http.Header
+ req, err := http.NewRequest(http.MethodGet, "http://example.com", nil)
+ require.NoError(t, err)
+ _, err = newSession(&got).RoundTrip(req)
+ require.NoError(t, err)
+ assert.Equal(t, []string{defaultAccessDelegation}, got.Values(headerIcebergAccessDelegation))
+ })
+
+ t.Run("per-request value overrides default without duplicating", func(t *testing.T) {
+ t.Parallel()
+
+ var got http.Header
+ req, err := http.NewRequest(http.MethodGet, "http://example.com", nil)
+ require.NoError(t, err)
+ req.Header.Set(headerIcebergAccessDelegation, "remote-signing")
+ _, err = newSession(&got).RoundTrip(req)
+ require.NoError(t, err)
+ assert.Equal(t, []string{"remote-signing"}, got.Values(headerIcebergAccessDelegation))
+ })
+
+ t.Run("context suppression drops the default", func(t *testing.T) {
+ t.Parallel()
+
+ var got http.Header
+ ctx := withSuppressedHeadersCtx(context.Background(), []string{headerIcebergAccessDelegation})
+ req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://example.com", nil)
+ require.NoError(t, err)
+ _, err = newSession(&got).RoundTrip(req)
+ require.NoError(t, err)
+ assert.Empty(t, got.Values(headerIcebergAccessDelegation))
+ })
+}
+
+// staticAuthManager is a test AuthManager returning a fixed authorization header.
+type staticAuthManager struct {
+ key, value string
+}
+
+func (s staticAuthManager) AuthHeader() (string, string, error) { return s.key, s.value, nil }
+
+func TestRoundTripAuthManagerWinsOverPerRequestHeader(t *testing.T) {
+ t.Parallel()
+
+ // The generalized per-request override lets withHeaders replace a session
+ // default of the same key, but the managed Authorization header must still
+ // win: authManager runs after the default-header loop and Set-overwrites, so
+ // a caller cannot suppress or spoof it via withHeaders. This pins that
+ // ordering, which is load-bearing but otherwise implicit.
+ var got http.Header
+ s := &sessionTransport{
+ RoundTripper: roundTripFunc(func(r *http.Request) (*http.Response, error) {
+ got = r.Header.Clone()
+
+ return &http.Response{StatusCode: http.StatusOK, Body: http.NoBody}, nil
+ }),
+ defaultHeaders: http.Header{},
+ authManager: staticAuthManager{key: "Authorization", value: "Bearer managed-token"},
+ }
+
+ req, err := http.NewRequest(http.MethodGet, "http://example.com", nil)
+ require.NoError(t, err)
+ req.Header.Set("Authorization", "Bearer caller-supplied")
+
+ _, err = s.RoundTrip(req)
+ require.NoError(t, err)
+ assert.Equal(t, []string{"Bearer managed-token"}, got.Values("Authorization"))
+}
+
+func TestReqOptionsCompose(t *testing.T) {
+ t.Parallel()
+
+ cfg := newReqConfig([]reqOption{
+ withHeaders(map[string]string{"X-First": "one"}),
+ withHeaders(map[string]string{"X-Second": "two"}),
+ withSuppressedHeaders("X-First"),
+ withSuppressedHeaders("X-Second", "X-Third"),
+ })
+
+ assert.Equal(t, map[string]string{
+ "X-First": "one",
+ "X-Second": "two",
+ }, cfg.headers)
+ assert.Equal(t, []string{"X-First", "X-Second", "X-Third"}, cfg.suppressHeaders)
+}
+
type closeTrackingReadCloser struct {
*bytes.Reader
closeErr error
@@ -1214,22 +1319,22 @@ func TestResponseBodyLeak(t *testing.T) {
baseURI, err := url.Parse(srv.URL)
require.NoError(t, err)
- _, err = do[struct{}](context.Background(), http.MethodGet, baseURI, []string{"test"}, client, nil, false)
+ _, err = do[struct{}](context.Background(), http.MethodGet, baseURI, []string{"test"}, client, nil)
require.Error(t, err)
assert.True(t, tracker.body.closed,
"response body should be closed on non-200 status")
})
- t.Run("doPostAllowNoContent", func(t *testing.T) {
+ t.Run("doPost", func(t *testing.T) {
tracker := &trackingTransport{transport: http.DefaultTransport}
client := &http.Client{Transport: tracker}
baseURI, err := url.Parse(srv.URL)
require.NoError(t, err)
- _, err = doPostAllowNoContent[map[string]string, struct{}](
- context.Background(), baseURI, []string{"test"}, map[string]string{"key": "value"}, client, nil, false)
+ _, err = doPost[map[string]string, struct{}](
+ context.Background(), baseURI, []string{"test"}, map[string]string{"key": "value"}, client, nil, allowNoContent())
require.Error(t, err)
assert.True(t, tracker.body.closed,
@@ -1244,7 +1349,7 @@ func TestHandleNon200_DecodeFlatMessagePreservesSentinel(t *testing.T) {
Body: io.NopCloser(bytes.NewBufferString(`{"message":"flat error"}`)),
}
- err := handleNon200(rsp, nil)
+ err := handleNon200(rsp, nil, nil)
require.Error(t, err)
require.Equal(t, "flat error", err.Error())
require.True(t, errors.Is(err, ErrBadRequest))
@@ -1257,7 +1362,7 @@ func TestHandleNon200_DecodeCanonicalErrorRendersExpectedMessage(t *testing.T) {
Body: io.NopCloser(bytes.NewBufferString(`{"error":{"message":"nested error","type":"ValidationException"}}`)),
}
- err := handleNon200(rsp, nil)
+ err := handleNon200(rsp, nil, nil)
require.Error(t, err)
require.Equal(t, "ValidationException: nested error", err.Error())
require.True(t, errors.Is(err, ErrForbidden))
@@ -1270,13 +1375,66 @@ func TestHandleNon200_EmptyBodyFallback(t *testing.T) {
Body: http.NoBody,
}
- err := handleNon200(rsp, nil)
+ err := handleNon200(rsp, nil, nil)
require.Error(t, err)
require.True(t, errors.Is(err, ErrBadRequest))
require.Equal(t, ErrBadRequest.Error(), err.Error())
require.NotEqual(t, ": ", err.Error())
}
+func TestHandleNon200_ErrorTypeOverride(t *testing.T) {
+ t.Parallel()
+
+ sentinelByType := errors.New("mapped by type")
+ sentinelByStatus := errors.New("mapped by status")
+ typeOverride := map[string]error{"NoSuchThingException": sentinelByType}
+ statusOverride := map[int]error{http.StatusNotFound: sentinelByStatus}
+
+ newRsp := func(status int, body string) *http.Response {
+ return &http.Response{
+ StatusCode: status,
+ ContentLength: int64(len(body)),
+ Body: io.NopCloser(bytes.NewBufferString(body)),
+ }
+ }
+
+ t.Run("error.type override wins over status override", func(t *testing.T) {
+ t.Parallel()
+
+ err := handleNon200(newRsp(http.StatusNotFound, `{"error":{"type":"NoSuchThingException","message":"gone"}}`), statusOverride, typeOverride)
+ require.ErrorIs(t, err, sentinelByType)
+ assert.NotErrorIs(t, err, sentinelByStatus)
+ })
+
+ t.Run("unmatched error.type falls through to status override", func(t *testing.T) {
+ t.Parallel()
+
+ err := handleNon200(newRsp(http.StatusNotFound, `{"error":{"type":"SomethingElse","message":"gone"}}`), statusOverride, typeOverride)
+ require.ErrorIs(t, err, sentinelByStatus)
+ assert.NotErrorIs(t, err, sentinelByType)
+ })
+
+ t.Run("empty body falls through to status override", func(t *testing.T) {
+ t.Parallel()
+
+ rsp := &http.Response{StatusCode: http.StatusNotFound, ContentLength: 0, Body: http.NoBody}
+ err := handleNon200(rsp, statusOverride, typeOverride)
+ require.ErrorIs(t, err, sentinelByStatus)
+ assert.NotErrorIs(t, err, sentinelByType)
+ })
+
+ t.Run("type override ignored on an unmapped status", func(t *testing.T) {
+ t.Parallel()
+
+ // The error.type values are defined for 404 in the spec; a 503 carrying
+ // one must resolve on status (ErrServiceUnavailable), not a 404 sentinel.
+ err := handleNon200(newRsp(http.StatusServiceUnavailable, `{"error":{"type":"NoSuchThingException","message":"down"}}`), statusOverride, typeOverride)
+ require.ErrorIs(t, err, ErrServiceUnavailable)
+ assert.NotErrorIs(t, err, sentinelByType)
+ assert.NotErrorIs(t, err, sentinelByStatus)
+ })
+}
+
func TestErrorResponse_ErrorFormattingTypeAndMessage(t *testing.T) {
err := errorResponse{Type: "ValidationException", Message: "bad request"}
require.Equal(t, "ValidationException: bad request", err.Error())
diff --git a/catalog/rest/scan_planning.go b/catalog/rest/scan_planning.go
index 062567f3..582dd58d 100644
--- a/catalog/rest/scan_planning.go
+++ b/catalog/rest/scan_planning.go
@@ -15,13 +15,10 @@
// specific language governing permissions and limitations
// under the License.
-// This file is a PROPOSED public API surface for REST server-side scan
-// planning (apache/iceberg-go#1178). The method bodies are intentionally
-// unimplemented stubs (returning ErrNotImplemented) so the REST surface can be
-// reviewed as Go — with one exception: PlanTableScanResponse.UnmarshalJSON
-// validates the status/plan-id union (with tests), added per review.
-// Endpoint capability discovery (Endpoint, SupportsEndpoint) lands separately
-// in the Phase 0 PR and is intentionally not redeclared here.
+// This file contains the REST server-side scan planning client surface for
+// apache/iceberg-go#1178. Low-level client methods and endpoint capability
+// checks are implemented here; higher-level orchestration, scanner delegation,
+// expression wrappers, and scan-task content decoding land in follow-up phases.
package rest
@@ -29,44 +26,152 @@ import (
"context"
"encoding/json"
"fmt"
+ "net/http"
+ "net/url"
+ "strings"
"time"
"github.com/apache/iceberg-go"
+ "github.com/apache/iceberg-go/catalog"
"github.com/apache/iceberg-go/table"
+ "github.com/google/uuid"
)
// Compile-time proof that the REST catalog satisfies the table planner seam.
var _ table.ScanPlanner = (*Catalog)(nil)
-// ErrPlanExpired is returned when polling a plan-id the server no longer knows
-// about (HTTP 404 while polling), distinct from a table-not-found 404.
+// ErrPlanExpired is returned when polling a plan that the server no longer
+// knows about: a fetchPlanningResult 404 whose error.type is exactly
+// NoSuchPlanIdException. It is distinct from a table/namespace-gone 404
+// (catalog.ErrNoSuchTable / catalog.ErrNoSuchNamespace) so the polling layer can
+// tell retry-with-a-new-plan from abort. A bare or unrecognized 404 stays an
+// ambiguous ErrRESTError rather than being guessed as an expiry.
var ErrPlanExpired = fmt.Errorf("%w: scan plan expired", ErrRESTError)
-// --- Capability gating (Open Question 2) ------------------------------------
+// ErrNoSuchPlanTask is returned when fetchScanTasks is called with a plan-task
+// handle the server no longer knows about: a 404 whose error.type is
+// NoSuchPlanTaskException. It is distinct from a table/namespace-gone 404 so a
+// caller fanning out over plan-task handles can tell an expired handle from the
+// table having vanished.
+var ErrNoSuchPlanTask = fmt.Errorf("%w: scan plan task not found", ErrRESTError)
+
+// ErrPlanFailed is returned by PlanTableScan and FetchPlanningResult when the
+// server reports a failed plan. The returned error is a *PlanFailedError, so the
+// structured PlanningError detail is reachable via errors.As.
+var ErrPlanFailed = fmt.Errorf("%w: scan plan failed", ErrRESTError)
+
+// ErrPlanCancelled is returned by FetchPlanningResult when polling a plan that
+// was cancelled (by this client or another). Like a failed plan it is terminal,
+// so it surfaces as an error rather than a (resp, nil) the if-err idiom skips.
+var ErrPlanCancelled = fmt.Errorf("%w: scan plan cancelled", ErrRESTError)
+
+// REST error.type values the scan-planning 404 responses carry. The spec models
+// a 404 on these endpoints as one of several distinct not-found conditions;
+// each maps to its own sentinel so the polling/fanout layer can tell a
+// retry-able expiry from a table/namespace-gone abort. Only these recognized
+// types get a specific sentinel; a bare or unrecognized 404 provides no basis to
+// choose one over another and stays an ambiguous ErrRESTError (the status-code
+// fallback). The strings are the ErrorModel `type` values from the REST OpenAPI
+// spec (the exception class simple names Java's RESTCatalog raises).
+const (
+ errTypeNoSuchPlanID = "NoSuchPlanIdException"
+ errTypeNoSuchPlanTask = "NoSuchPlanTaskException"
+ errTypeNoSuchTable = "NoSuchTableException"
+ errTypeNoSuchNamespace = "NoSuchNamespaceException"
+)
+
+// planTableScanErrorTypes splits a POST .../plan 404 by error.type: the plan
+// endpoint takes an identifier but no plan-id, so a recognized 404 is a missing
+// table or namespace. An unrecognized 404 stays ErrRESTError.
+var planTableScanErrorTypes = map[string]error{
+ errTypeNoSuchTable: catalog.ErrNoSuchTable,
+ errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace,
+}
+
+// fetchPlanningResultErrorTypes splits a GET .../plan/{plan-id} 404: a forgotten
+// plan-id is retry-with-a-new-plan (ErrPlanExpired), while a gone table or
+// namespace is an abort. An unrecognized 404 stays ErrRESTError.
+var fetchPlanningResultErrorTypes = map[string]error{
+ errTypeNoSuchPlanID: ErrPlanExpired,
+ errTypeNoSuchTable: catalog.ErrNoSuchTable,
+ errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace,
+}
+
+// fetchScanTasksErrorTypes splits a POST .../tasks 404: an expired plan-task
+// handle (ErrNoSuchPlanTask) is distinct from a gone table or namespace. An
+// unrecognized 404 stays ErrRESTError.
+var fetchScanTasksErrorTypes = map[string]error{
+ errTypeNoSuchPlanTask: ErrNoSuchPlanTask,
+ errTypeNoSuchTable: catalog.ErrNoSuchTable,
+ errTypeNoSuchNamespace: catalog.ErrNoSuchNamespace,
+}
+
+// PlanFailedError carries the server's structured PlanningError detail for a
+// failed plan. It satisfies errors.Is(err, ErrPlanFailed) so callers can branch
+// on the failure with the if-err idiom while still reaching the detail via
+// errors.As.
+type PlanFailedError struct {
+ Detail *PlanningError
+}
+
+func (e *PlanFailedError) Error() string {
+ if e.Detail != nil && e.Detail.Message != "" {
+ return ErrPlanFailed.Error() + ": " + e.Detail.Message
+ }
+
+ return ErrPlanFailed.Error()
+}
+
+func (e *PlanFailedError) Unwrap() error { return ErrPlanFailed }
+
+// headerIdempotencyKey is the per-request idempotency key on the plan and tasks
+// POSTs. The access-delegation header name lives in rest.go because it is also
+// a session default.
+const headerIdempotencyKey = "Idempotency-Key"
+
+// --- Capability gating -------------------------------------------------------
//
-// A single capability check is too coarse: requiring all four endpoints falls
-// back to local against sync-only servers, while requiring only the plan
-// endpoint false-positives, because planTableScan can return `submitted` or
-// `plan-tasks` that need the poll/fetch endpoints. The split below lets `auto`
-// use a sync-only server while reserving the async/fanout path for servers
-// that advertise everything.
+// Capability is split into two predicates. SupportsPlanTableScan is the narrow
+// "server can plan inline" check (plan endpoint only). SupportsFullRemoteScanPlanning
+// is the endpoint-level "server advertises all four endpoints" check: an
+// end-to-end plan can come back `submitted` or with `plan-tasks` that need the
+// poll/cancel/fetch endpoints to finish, and auto mode has no second chance to
+// fall back to local once it commits to remote, so a plan-only server must not
+// count as end-to-end capable.
+//
+// SupportsRemoteScanPlanning is the table.ScanPlanner-facing predicate that
+// table.Scan's auto mode routes on. It is deliberately gated to false while
+// PlanFiles is an unimplemented stub: routing on endpoint capability alone would
+// send an auto-mode scan into PlanFiles and surface ErrNotImplemented instead of
+// falling back to local planning. It flips on with the PlanFiles phase.
// SupportsPlanTableScan reports whether the server advertised the synchronous
// plan endpoint.
func (r *Catalog) SupportsPlanTableScan() bool {
- return false
+ return r.endpoints.contains(endpointPlanTableScan)
}
// SupportsFullRemoteScanPlanning reports whether the server advertised all four
-// scan-planning endpoints (plan, fetch-result, cancel, fetch-tasks).
+// scan-planning endpoints (plan, fetch-result, cancel, fetch-tasks), i.e. it can
+// drive the async/fanout path, not just sync inline planning.
func (r *Catalog) SupportsFullRemoteScanPlanning() bool {
- return false
+ return r.SupportsPlanTableScan() &&
+ r.endpoints.contains(endpointFetchPlanResult) &&
+ r.endpoints.contains(endpointCancelPlanning) &&
+ r.endpoints.contains(endpointFetchScanTasks)
}
// --- table.ScanPlanner implementation ---------------------------------------
// SupportsRemoteScanPlanning reports whether this catalog can complete a remote
-// plan end-to-end; backed by the split capability checks above.
+// plan end-to-end. table.Scan's auto mode routes on it, calling PlanFiles when it
+// is true, so it must stay false until PlanFiles is implemented — otherwise an
+// auto-mode scan against a server advertising all four endpoints would fail with
+// ErrNotImplemented instead of falling back to local planning.
+//
+// TODO(#1178): return SupportsFullRemoteScanPlanning() once PlanFiles is wired
+// end-to-end. Until then, callers probing endpoint capability should use
+// SupportsFullRemoteScanPlanning / SupportsPlanTableScan directly.
func (r *Catalog) SupportsRemoteScanPlanning() bool {
return false
}
@@ -79,30 +184,145 @@ func (r *Catalog) PlanFiles(ctx context.Context, req table.ScanPlanningRequest)
// --- Low-level client methods -----------------------------------------------
-// PlanTableScan submits a scan plan. The result is either completed inline,
-// submitted (returns a plan-id to poll), or failed.
+// PlanTableScan submits a scan plan. A completed or submitted plan returns
+// (resp, nil); callers branch on resp.Status for the plan-id (completed) vs
+// poll (submitted) distinction. A failed plan returns a zero response and a
+// non-nil *PlanFailedError (errors.Is(err, ErrPlanFailed)) so the if-err idiom
+// does not mistake a failure for success; the server detail rides on the error.
+// Any other status — including the empty status of a 200 with no body, which
+// bypasses the response UnmarshalJSON validation — returns an ErrRESTError so a
+// malformed response cannot masquerade as an empty completed plan.
func (r *Catalog) PlanTableScan(ctx context.Context, ident table.Identifier, req PlanTableScanRequest) (PlanTableScanResponse, error) {
- return PlanTableScanResponse{}, fmt.Errorf("%w: plan table scan", iceberg.ErrNotImplemented)
+ if err := r.endpoints.check(endpointPlanTableScan); err != nil {
+ return PlanTableScanResponse{}, err
+ }
+
+ path, err := r.scanPlanningPath(endpointPlanTableScan, ident)
+ if err != nil {
+ return PlanTableScanResponse{}, err
+ }
+
+ headers, err := scanPlanningHeaders(req.IdempotencyKey, req.AccessDelegation, true)
+ if err != nil {
+ return PlanTableScanResponse{}, err
+ }
+
+ resp, err := doPost[PlanTableScanRequest, PlanTableScanResponse](
+ ctx, r.baseURI, path, req, r.cl,
+ map[int]error{http.StatusNotFound: ErrRESTError},
+ withHeaders(headers), withErrorTypeOverride(planTableScanErrorTypes))
+ if err != nil {
+ return PlanTableScanResponse{}, err
+ }
+ switch resp.Status {
+ case PlanStatusCompleted, PlanStatusSubmitted:
+ return resp, nil
+ case PlanStatusFailed:
+ return PlanTableScanResponse{}, &PlanFailedError{Detail: resp.Error}
+ default:
+ return PlanTableScanResponse{}, fmt.Errorf(
+ "%w: planTableScan response has invalid status %q", ErrRESTError, resp.Status)
+ }
}
// FetchPlanningResult polls a previously submitted plan. opts.AccessDelegation
// is sent as the X-Iceberg-Access-Delegation header so an async poll can still
// receive plan-scoped storage credentials: the spec defines data-access on this
// endpoint, and the completed-async result is where those credentials are vended.
+//
+// completed and submitted return (resp, nil) and callers branch on resp.Status
+// (done vs poll again). The terminal failure states surface as errors so an
+// if-err poll loop cannot mistake them for an empty scan: failed returns a
+// *PlanFailedError (errors.Is(err, ErrPlanFailed)) and cancelled returns
+// ErrPlanCancelled. A 404 is split by the response error.type: a forgotten
+// plan-id (NoSuchPlanIdException) is ErrPlanExpired, while a gone table or
+// namespace is catalog.ErrNoSuchTable / catalog.ErrNoSuchNamespace, so the poller
+// can tell retry-with-a-new-plan from abort. A bare or unrecognized 404 stays an
+// ambiguous ErrRESTError rather than being guessed as an expiry.
func (r *Catalog) FetchPlanningResult(ctx context.Context, ident table.Identifier, planID string, opts FetchPlanningResultOptions) (FetchPlanningResultResponse, error) {
- return FetchPlanningResultResponse{}, fmt.Errorf("%w: fetch planning result", iceberg.ErrNotImplemented)
+ if err := r.endpoints.check(endpointFetchPlanResult); err != nil {
+ return FetchPlanningResultResponse{}, err
+ }
+
+ path, err := r.scanPlanningPath(endpointFetchPlanResult, ident, planID)
+ if err != nil {
+ return FetchPlanningResultResponse{}, err
+ }
+
+ headers, err := scanPlanningHeaders(nil, opts.AccessDelegation, false)
+ if err != nil {
+ return FetchPlanningResultResponse{}, err
+ }
+
+ resp, err := doGet[FetchPlanningResultResponse](
+ ctx, r.baseURI, path, r.cl,
+ map[int]error{http.StatusNotFound: ErrRESTError},
+ withHeaders(headers), withErrorTypeOverride(fetchPlanningResultErrorTypes))
+ if err != nil {
+ return FetchPlanningResultResponse{}, err
+ }
+ switch resp.Status {
+ case PlanStatusFailed:
+ return FetchPlanningResultResponse{}, &PlanFailedError{Detail: resp.Error}
+ case PlanStatusCancelled:
+ return FetchPlanningResultResponse{}, ErrPlanCancelled
+ }
+
+ return resp, nil
}
// CancelPlanning cancels a server-side plan. Callers should cancel on context
-// cancellation using a detached context with a short timeout.
+// cancellation using a detached context with a short timeout. The spec supports
+// idempotency and access-delegation headers on cancel; this low-level method
+// deliberately defers those until a cancel options type is added, and suppresses
+// the session-default access-delegation header (cancel vends no credentials). A
+// 404 (already-expired or unknown plan) is not special-cased: cancel is
+// best-effort, so the generic REST error is acceptable.
func (r *Catalog) CancelPlanning(ctx context.Context, ident table.Identifier, planID string) error {
- return fmt.Errorf("%w: cancel planning", iceberg.ErrNotImplemented)
+ if err := r.endpoints.check(endpointCancelPlanning); err != nil {
+ return err
+ }
+
+ path, err := r.scanPlanningPath(endpointCancelPlanning, ident, planID)
+ if err != nil {
+ return err
+ }
+
+ _, err = doDelete[struct{}](
+ ctx, r.baseURI, path, r.cl, nil,
+ withSuppressedHeaders(headerIcebergAccessDelegation))
+
+ return err
}
// FetchScanTasks fetches the scan tasks for a plan-task handle returned by a
-// completed plan.
+// completed plan. A 404 is split by the response error.type: an expired
+// plan-task handle (NoSuchPlanTaskException) is ErrNoSuchPlanTask, while a gone
+// table or namespace is catalog.ErrNoSuchTable / catalog.ErrNoSuchNamespace, so
+// a caller fanning out over handles can tell a handle expiry from the table
+// vanishing. A bare or unrecognized 404 stays an ambiguous ErrRESTError. An
+// empty 200 body is rejected (requireBody) so a truncated response is not read
+// as a successfully completed empty task set.
func (r *Catalog) FetchScanTasks(ctx context.Context, ident table.Identifier, req FetchScanTasksRequest) (FetchScanTasksResponse, error) {
- return FetchScanTasksResponse{}, fmt.Errorf("%w: fetch scan tasks", iceberg.ErrNotImplemented)
+ if err := r.endpoints.check(endpointFetchScanTasks); err != nil {
+ return FetchScanTasksResponse{}, err
+ }
+
+ path, err := r.scanPlanningPath(endpointFetchScanTasks, ident)
+ if err != nil {
+ return FetchScanTasksResponse{}, err
+ }
+
+ headers, err := scanPlanningHeaders(req.IdempotencyKey, nil, true)
+ if err != nil {
+ return FetchScanTasksResponse{}, err
+ }
+
+ return doPost[FetchScanTasksRequest, FetchScanTasksResponse](
+ ctx, r.baseURI, path, req, r.cl,
+ map[int]error{http.StatusNotFound: ErrRESTError},
+ withHeaders(headers), withSuppressedHeaders(headerIcebergAccessDelegation),
+ withErrorTypeOverride(fetchScanTasksErrorTypes), requireBody())
}
// WaitForPlan polls a submitted plan to completion using jittered backoff,
@@ -113,6 +333,101 @@ func (r *Catalog) WaitForPlan(ctx context.Context, ident table.Identifier, planI
return CompletedPlanningResult{}, fmt.Errorf("%w: wait for plan", iceberg.ErrNotImplemented)
}
+func (r *Catalog) scanPlanningPath(ep endpoint, ident table.Identifier, extra ...string) ([]string, error) {
+ ns, tbl, err := r.splitIdentForPath(ident)
+ if err != nil {
+ return nil, err
+ }
+
+ // extra carries opaque, server-issued path segments (the plan-id). The spec
+ // puts no character restriction on them, and baseURI.JoinPath path.Cleans its
+ // arguments — so an unescaped id containing '/' would split into segments and
+ // a '..'/'.' segment would resolve to a different endpoint (e.g. ".." on the
+ // plan path lands on .../tasks). Escape each as a single literal path segment.
+ params := make([]string, 0, 2+len(extra))
+ params = append(params, ns, tbl)
+ for _, seg := range extra {
+ params = append(params, escapeOpaquePathSegment(seg))
+ }
+
+ return ep.reqPath(params...)
+}
+
+// escapeOpaquePathSegment percent-encodes an opaque string so it survives
+// url.URL.JoinPath as a single literal path segment. url.PathEscape handles '/',
+// '%', spaces, etc., but leaves a pure-dot segment ("." or "..") unescaped, which
+// JoinPath's path.Clean would then resolve as a dot-segment; encode those dots so
+// the segment is preserved verbatim.
+func escapeOpaquePathSegment(s string) string {
+ switch escaped := url.PathEscape(s); escaped {
+ case ".":
+ return "%2E"
+ case "..":
+ return "%2E%2E"
+ default:
+ return escaped
+ }
+}
+
+func scanPlanningHeaders(idempotencyKey, accessDelegation *string, includeIdempotency bool) (map[string]string, error) {
+ headers := make(map[string]string, 2)
+ if includeIdempotency {
+ key, err := idempotencyHeaderValue(idempotencyKey)
+ if err != nil {
+ return nil, err
+ }
+ headers[headerIdempotencyKey] = key
+ }
+ if accessDelegation != nil {
+ headers[headerIcebergAccessDelegation] = *accessDelegation
+ }
+ if len(headers) == 0 {
+ return nil, nil
+ }
+
+ return headers, nil
+}
+
+func idempotencyHeaderValue(idempotencyKey *string) (string, error) {
+ if idempotencyKey == nil {
+ // Plan and task POSTs always send an idempotency key. The spec pins it
+ // to a UUIDv7 string (RFC 9562) so a server can key its dedup window off
+ // the embedded timestamp, matching Java's UUIDUtil.generateUuidV7(). A
+ // v4 key would be treated as undefined by such servers. There is no
+ // transport retry here, so nil means a fresh key for this call.
+ key, err := uuid.NewV7()
+ if err != nil {
+ return "", fmt.Errorf("generating idempotency key: %w", err)
+ }
+
+ return key.String(), nil
+ }
+
+ parsed, err := uuid.Parse(*idempotencyKey)
+ if err != nil {
+ return "", fmt.Errorf("%w: invalid idempotency key %q", iceberg.ErrInvalidArgument, *idempotencyKey)
+ }
+ // uuid.Parse is lenient (its docs say it should not be used for validation):
+ // it accepts the URN, brace, and un-hyphenated 32-char forms. The spec's
+ // header schema pins this to the 36-char canonical hyphenated form, so reject
+ // anything whose canonical rendering differs (case-insensitively) from the
+ // input rather than forward a nonconforming encoding.
+ if !strings.EqualFold(parsed.String(), *idempotencyKey) {
+ return "", fmt.Errorf("%w: idempotency key %q must be a canonical hyphenated UUID",
+ iceberg.ErrInvalidArgument, *idempotencyKey)
+ }
+ // The spec pins the header to UUIDv7, so reject other versions rather than
+ // forward a key a timestamp-keyed server would treat as undefined. RFC 9562
+ // UUIDv7 also uses the RFC 4122 variant, so require that too: a canonical
+ // string can carry the version-7 nibble while setting non-RFC variant bits.
+ if parsed.Version() != 7 || parsed.Variant() != uuid.RFC4122 {
+ return "", fmt.Errorf("%w: idempotency key %q must be an RFC 4122 UUIDv7 (got v%d, variant %v)",
+ iceberg.ErrInvalidArgument, *idempotencyKey, int(parsed.Version()), parsed.Variant())
+ }
+
+ return *idempotencyKey, nil
+}
+
// --- Wire types (sketch) ----------------------------------------------------
//
// Content-file, delete-file, and residual decoding lands with the scan-task
@@ -180,8 +495,10 @@ type CompletedPlanningResult struct {
// wire type and the seam stay in agreement.
type PlanTableScanRequest struct {
// IdempotencyKey is sent as the Idempotency-Key header, not in the JSON body.
- // If set, it must be a UUID string; nil lets the implementation choose a
- // safe retry key.
+ // If set, it must be a UUIDv7 string (RFC 9562). If nil, a fresh UUIDv7 is
+ // generated per call and not returned, so passing nil and retrying on a
+ // transient error sends a different key each attempt and defeats server-side
+ // dedup: pass an explicit key to get idempotency across retries.
IdempotencyKey *string `json:"-"`
// AccessDelegation is sent as the X-Iceberg-Access-Delegation header, not
// in the JSON body. Nil uses the catalog default.
@@ -249,11 +566,35 @@ type FetchPlanningResultResponse struct {
StorageCredentials []StorageCredential `json:"storage-credentials,omitempty"`
}
+func (r *FetchPlanningResultResponse) UnmarshalJSON(data []byte) error {
+ type fetchPlanningResultResponse FetchPlanningResultResponse
+ var resp fetchPlanningResultResponse
+ if err := json.Unmarshal(data, &resp); err != nil {
+ return err
+ }
+
+ switch resp.Status {
+ case PlanStatusCompleted, PlanStatusSubmitted, PlanStatusCancelled:
+ case PlanStatusFailed:
+ if resp.Error == nil {
+ return fmt.Errorf("%w: fetchPlanningResult failed response missing error", ErrRESTError)
+ }
+ default:
+ return fmt.Errorf("%w: fetchPlanningResult response has unknown status %q", ErrRESTError, resp.Status)
+ }
+
+ *r = FetchPlanningResultResponse(resp)
+
+ return nil
+}
+
// FetchScanTasksRequest is the POST .../tasks request body.
type FetchScanTasksRequest struct {
// IdempotencyKey is sent as the Idempotency-Key header, not in the JSON body.
- // If set, it must be a UUID string; nil lets the implementation choose a
- // safe retry key.
+ // If set, it must be a UUIDv7 string (RFC 9562). If nil, a fresh UUIDv7 is
+ // generated per call and not returned, so passing nil and retrying on a
+ // transient error sends a different key each attempt and defeats server-side
+ // dedup: pass an explicit key to get idempotency across retries.
IdempotencyKey *string `json:"-"`
PlanTask string `json:"plan-task"`
diff --git a/catalog/rest/scan_planning_test.go b/catalog/rest/scan_planning_test.go
index 56c990c0..fbddd9ec 100644
--- a/catalog/rest/scan_planning_test.go
+++ b/catalog/rest/scan_planning_test.go
@@ -18,13 +18,142 @@
package rest
import (
+ "context"
"encoding/json"
+ "fmt"
+ "io"
+ "net/http"
+ "net/http/httptest"
+ "net/url"
+ "strings"
"testing"
+ "github.com/apache/iceberg-go"
+ "github.com/apache/iceberg-go/catalog"
+ "github.com/apache/iceberg-go/table"
+ "github.com/google/uuid"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
)
+func TestScanPlanningEndpointConstantsRenderExpectedPaths(t *testing.T) {
+ t.Parallel()
+
+ cases := []struct {
+ name string
+ ep endpoint
+ params []string
+ want []string
+ }{
+ {
+ name: "plan table scan",
+ ep: endpointPlanTableScan,
+ params: []string{"db", "tbl"},
+ want: []string{"namespaces", "db", "tables", "tbl", "plan"},
+ },
+ {
+ name: "fetch planning result",
+ ep: endpointFetchPlanResult,
+ params: []string{"db", "tbl", "plan-123"},
+ want: []string{"namespaces", "db", "tables", "tbl", "plan", "plan-123"},
+ },
+ {
+ name: "cancel planning",
+ ep: endpointCancelPlanning,
+ params: []string{"db", "tbl", "plan-123"},
+ want: []string{"namespaces", "db", "tables", "tbl", "plan", "plan-123"},
+ },
+ {
+ name: "fetch scan tasks",
+ ep: endpointFetchScanTasks,
+ params: []string{"db", "tbl"},
+ want: []string{"namespaces", "db", "tables", "tbl", "tasks"},
+ },
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ got, err := tc.ep.reqPath(tc.params...)
+ require.NoError(t, err)
+ assert.Equal(t, tc.want, got)
+ })
+ }
+}
+
+func TestScanPlanningEscapesOpaquePlanID(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, nil)
+
+ // baseURI.JoinPath path.Cleans its segments, so scanPlanningPath must escape
+ // an opaque plan-id containing '/', a dot segment, or traversal into a single
+ // literal segment; otherwise "a/b" splits and ".." / "../tasks" resolve to a
+ // different endpoint. Each must survive JoinPath as the final .../plan/ segment
+ // and round-trip.
+ for _, planID := range []string{"a/b", "../tasks", "a b", "a%2Fb", ".", "..", "plan-123"} {
+ path, err := cat.scanPlanningPath(endpointFetchPlanResult, table.Identifier{"db", "tbl"}, planID)
+ require.NoErrorf(t, err, "plan-id %q", planID)
+
+ seg := path[len(path)-1]
+ assert.NotContainsf(t, seg, "/", "plan-id %q split into multiple segments: %q", planID, seg)
+
+ decoded, err := url.PathUnescape(seg)
+ require.NoErrorf(t, err, "plan-id %q", planID)
+ assert.Equalf(t, planID, decoded, "plan-id %q did not round-trip", planID)
+
+ // The escaped segment must survive JoinPath's path.Clean as the last
+ // .../plan/ segment (no split, no traversal to a different endpoint).
+ escaped := cat.baseURI.JoinPath(path...).EscapedPath()
+ assert.Truef(t, strings.HasSuffix(escaped, "/plan/"+seg),
+ "plan-id %q was mangled by JoinPath: %s", planID, escaped)
+ }
+}
+
+func TestScanPlanningCapabilities(t *testing.T) {
+ t.Parallel()
+
+ t.Run("plan only", func(t *testing.T) {
+ t.Parallel()
+
+ // A plan-only server can plan inline, but a `submitted` reply could not
+ // be polled, so it is not full-remote capable. SupportsRemoteScanPlanning
+ // is false here too (gated off while PlanFiles is a stub).
+ cat := &Catalog{endpoints: newEndpointSet([]endpoint{endpointPlanTableScan})}
+ assert.True(t, cat.SupportsPlanTableScan())
+ assert.False(t, cat.SupportsFullRemoteScanPlanning())
+ assert.False(t, cat.SupportsRemoteScanPlanning())
+ })
+
+ t.Run("full remote planning", func(t *testing.T) {
+ t.Parallel()
+
+ cat := &Catalog{endpoints: newEndpointSet([]endpoint{
+ endpointPlanTableScan,
+ endpointFetchPlanResult,
+ endpointCancelPlanning,
+ endpointFetchScanTasks,
+ })}
+ assert.True(t, cat.SupportsPlanTableScan())
+ assert.True(t, cat.SupportsFullRemoteScanPlanning())
+ // SupportsRemoteScanPlanning stays false while PlanFiles is a stub, even
+ // when all four endpoints are advertised, so auto mode falls back to
+ // local instead of routing into ErrNotImplemented. Flips on with the
+ // PlanFiles phase.
+ assert.False(t, cat.SupportsRemoteScanPlanning())
+ })
+
+ t.Run("default fallback does not advertise scan planning", func(t *testing.T) {
+ t.Parallel()
+
+ cat := &Catalog{endpoints: newEndpointSet(defaultEndpoints)}
+ assert.False(t, cat.SupportsPlanTableScan())
+ assert.False(t, cat.SupportsFullRemoteScanPlanning())
+ assert.False(t, cat.SupportsRemoteScanPlanning())
+ })
+}
+
func TestPlanTableScanResponseRequiresPlanIDForTrackedStatuses(t *testing.T) {
t.Parallel()
@@ -94,3 +223,581 @@ func TestPlanTableScanResponseRejectsUnknownStatus(t *testing.T) {
err := json.Unmarshal([]byte(`{"status":"bogus"}`), &resp)
require.ErrorIs(t, err, ErrRESTError)
}
+
+func TestFetchPlanningResultResponseRejectsMalformedResponses(t *testing.T) {
+ t.Parallel()
+
+ t.Run("failed without error", func(t *testing.T) {
+ t.Parallel()
+
+ var resp FetchPlanningResultResponse
+ err := json.Unmarshal([]byte(`{"status":"failed"}`), &resp)
+ require.ErrorIs(t, err, ErrRESTError)
+ })
+
+ t.Run("unknown status", func(t *testing.T) {
+ t.Parallel()
+
+ var resp FetchPlanningResultResponse
+ err := json.Unmarshal([]byte(`{"status":"bogus"}`), &resp)
+ require.ErrorIs(t, err, ErrRESTError)
+ })
+}
+
+func TestPlanTableScanGeneratesIdempotencyKeyAndUsesDefaultAccessDelegation(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+ got := req.Header.Get(headerIdempotencyKey)
+ require.NotEmpty(t, got)
+ parsed, err := uuid.Parse(got)
+ require.NoError(t, err)
+ // The spec pins the generated key to UUIDv7.
+ assert.Equal(t, 7, int(parsed.Version()))
+ assert.Equal(t, []string{defaultAccessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+ _, err = w.Write([]byte(`{"status":"completed","plan-id":"plan-1"}`))
+ require.NoError(t, err)
+ })
+ })
+
+ _, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{})
+ require.NoError(t, err)
+}
+
+func TestPlanTableScanRejectsInvalidIdempotencyKey(t *testing.T) {
+ t.Parallel()
+
+ for _, tc := range []struct {
+ name string
+ key string
+ }{
+ {"not a uuid", "not-a-uuid"},
+ // Valid UUID, but v1 not v7 — the spec pins the header to UUIDv7.
+ {"valid uuid wrong version", "11111111-1111-1111-1111-111111111111"},
+ // uuid.Parse accepts these non-canonical encodings of a valid v7 UUID,
+ // but the spec's header schema requires the 36-char hyphenated form.
+ {"unhyphenated v7", "0190b6c51c3d70008000000000000001"},
+ {"urn v7", "urn:uuid:0190b6c5-1c3d-7000-8000-000000000001"},
+ {"braced v7", "{0190b6c5-1c3d-7000-8000-000000000001}"},
+ // Canonical with the version-7 nibble but a non-RFC-4122 variant (the
+ // 4th group's leading nibble is 0 -> reserved/NCS, not 8-b).
+ {"v7 non-rfc variant", "0190b6c5-1c3d-7000-0000-000000000001"},
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ key := tc.key
+ cat := &Catalog{endpoints: newEndpointSet([]endpoint{endpointPlanTableScan})}
+
+ _, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{
+ IdempotencyKey: &key,
+ })
+ require.ErrorIs(t, err, iceberg.ErrInvalidArgument)
+ })
+ }
+}
+
+func TestPlanTableScanAcceptsUppercaseCanonicalIdempotencyKey(t *testing.T) {
+ t.Parallel()
+
+ // Canonical hyphenated form is required case-insensitively; an uppercase v7
+ // key is accepted and forwarded verbatim.
+ key := "0190B6C5-1C3D-7000-8000-000000000001"
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+ assert.Equal(t, key, req.Header.Get(headerIdempotencyKey))
+ _, err := w.Write([]byte(`{"status":"completed","plan-id":"plan-1"}`))
+ require.NoError(t, err)
+ })
+ })
+
+ _, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{
+ IdempotencyKey: &key,
+ })
+ require.NoError(t, err)
+}
+
+func TestPlanTableScanRequest(t *testing.T) {
+ t.Parallel()
+
+ cases := []struct {
+ name string
+ response string
+ wantStatus PlanStatus
+ wantPlanID *string
+ wantError string
+ }{
+ {
+ name: "completed",
+ response: `{"status":"completed","plan-id":"plan-1","plan-tasks":["task-1"]}`,
+ wantStatus: PlanStatusCompleted,
+ wantPlanID: stringPtr("plan-1"),
+ },
+ {
+ name: "submitted",
+ response: `{"status":"submitted","plan-id":"plan-2"}`,
+ wantStatus: PlanStatusSubmitted,
+ wantPlanID: stringPtr("plan-2"),
+ },
+ {
+ name: "failed",
+ response: `{"status":"failed","error":{"message":"boom","type":"ServerError","code":500}}`,
+ wantStatus: PlanStatusFailed,
+ wantError: "boom",
+ },
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ idempotencyKey := "0190b6c5-1c3d-7000-8000-000000000001"
+ accessDelegation := "remote-signing"
+ snapshotID := int64(22)
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodPost, req.Method)
+ assert.Equal(t, idempotencyKey, req.Header.Get(headerIdempotencyKey))
+ assert.Equal(t, []string{accessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+ body, err := io.ReadAll(req.Body)
+ require.NoError(t, err)
+ assert.JSONEq(t, `{
+ "snapshot-id": 22,
+ "select": ["id", "data"],
+ "filter": {"type": "always-true"}
+ }`, string(body))
+
+ _, err = w.Write([]byte(tc.response))
+ require.NoError(t, err)
+ })
+ })
+
+ resp, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{
+ IdempotencyKey: &idempotencyKey,
+ AccessDelegation: &accessDelegation,
+ SnapshotID: &snapshotID,
+ Select: []string{"id", "data"},
+ Filter: json.RawMessage(`{"type":"always-true"}`),
+ })
+ if tc.wantError != "" {
+ // A failed plan returns a *PlanFailedError and a zero resp; the
+ // detail rides on the error.
+ require.ErrorIs(t, err, ErrPlanFailed)
+ var pfe *PlanFailedError
+ require.ErrorAs(t, err, &pfe)
+ require.NotNil(t, pfe.Detail)
+ assert.Equal(t, tc.wantError, pfe.Detail.Message)
+ assert.Equal(t, PlanTableScanResponse{}, resp)
+
+ return
+ }
+
+ require.NoError(t, err)
+ assert.Equal(t, tc.wantStatus, resp.Status)
+ if tc.wantPlanID != nil {
+ require.NotNil(t, resp.PlanID)
+ assert.Equal(t, *tc.wantPlanID, *resp.PlanID)
+ }
+ })
+ }
+}
+
+func TestPlanTableScanRejectsEmptyBody(t *testing.T) {
+ t.Parallel()
+
+ // A 200 with an empty body skips JSON decoding (doPost short-circuits on
+ // Content-Length 0), bypassing the response UnmarshalJSON validation. Without
+ // a status guard this would return a zero response with a nil PlanID as
+ // success; assert it is rejected instead.
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodPost, req.Method)
+ w.Header().Set("Content-Length", "0")
+ w.WriteHeader(http.StatusOK)
+ })
+ })
+
+ resp, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{})
+ require.ErrorIs(t, err, ErrRESTError)
+ assert.Equal(t, PlanTableScanResponse{}, resp)
+}
+
+func TestFetchScanTasksRejectsEmptyBody(t *testing.T) {
+ t.Parallel()
+
+ // FetchScanTasks has no status discriminator, so an empty 200 (doPost
+ // short-circuits on Content-Length 0) would otherwise decode to a zero,
+ // task-less response and read as a successfully completed empty scan,
+ // silently dropping work. requireBody rejects it.
+ key := "0190b6c5-1c3d-7000-8000-000000000004"
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchScanTasks}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/tasks", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodPost, req.Method)
+ w.Header().Set("Content-Length", "0")
+ w.WriteHeader(http.StatusOK)
+ })
+ })
+
+ resp, err := cat.FetchScanTasks(context.Background(), table.Identifier{"db", "tbl"}, FetchScanTasksRequest{
+ IdempotencyKey: &key,
+ PlanTask: "task-1",
+ })
+ require.ErrorIs(t, err, ErrRESTError)
+ assert.Equal(t, FetchScanTasksResponse{}, resp)
+}
+
+func TestFetchPlanningResultRequest(t *testing.T) {
+ t.Parallel()
+
+ accessDelegation := "remote-signing"
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodGet, req.Method)
+ assert.Equal(t, []string{accessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+ _, err := w.Write([]byte(`{"status":"completed","plan-tasks":["task-1"]}`))
+ require.NoError(t, err)
+ })
+ })
+
+ resp, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{
+ AccessDelegation: &accessDelegation,
+ })
+ require.NoError(t, err)
+ assert.Equal(t, PlanStatusCompleted, resp.Status)
+ assert.Equal(t, []string{"task-1"}, resp.PlanTasks)
+}
+
+func TestFetchPlanningResultUsesDefaultAccessDelegation(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodGet, req.Method)
+ assert.Equal(t, []string{defaultAccessDelegation}, req.Header.Values(headerIcebergAccessDelegation))
+
+ _, err := w.Write([]byte(`{"status":"submitted"}`))
+ require.NoError(t, err)
+ })
+ })
+
+ resp, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+ require.NoError(t, err)
+ assert.Equal(t, PlanStatusSubmitted, resp.Status)
+}
+
+func TestFetchPlanningResultMapsNotFound(t *testing.T) {
+ t.Parallel()
+
+ // The GET .../plan/{plan-id} 404 splits on error.type so the poller can tell
+ // retry-with-a-new-plan (expired plan-id) from abort (table/namespace gone).
+ // A bare or unrecognized 404 is ambiguous and stays ErrRESTError rather than
+ // being guessed as an expiry (which would make a poller retry a gone table).
+ cases := []struct {
+ name string
+ errType string // empty => bare 404 with no body
+ wantErr error
+ notErr error
+ }{
+ {"bare 404", "", ErrRESTError, ErrPlanExpired},
+ {"unrecognized type", "SomeFutureException", ErrRESTError, ErrPlanExpired},
+ {"no such plan-id", errTypeNoSuchPlanID, ErrPlanExpired, catalog.ErrNoSuchTable},
+ {"no such table", errTypeNoSuchTable, catalog.ErrNoSuchTable, ErrPlanExpired},
+ {"no such namespace", errTypeNoSuchNamespace, catalog.ErrNoSuchNamespace, ErrPlanExpired},
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodGet, req.Method)
+ writeRESTNotFound(t, w, tc.errType)
+ })
+ })
+
+ _, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+ require.ErrorIs(t, err, tc.wantErr)
+ if tc.notErr != nil {
+ assert.NotErrorIs(t, err, tc.notErr)
+ }
+ })
+ }
+}
+
+func TestFetchScanTasksMapsNotFound(t *testing.T) {
+ t.Parallel()
+
+ // The POST .../tasks 404 splits on error.type so a fanout caller can tell an
+ // expired plan-task handle from the table/namespace having vanished. A bare
+ // or unrecognized 404 stays an ambiguous ErrRESTError.
+ cases := []struct {
+ name string
+ errType string // empty => bare 404 with no body
+ wantErr error
+ notErr error
+ }{
+ {"bare 404", "", ErrRESTError, ErrNoSuchPlanTask},
+ {"unrecognized type", "SomeFutureException", ErrRESTError, ErrNoSuchPlanTask},
+ {"no such plan-task", errTypeNoSuchPlanTask, ErrNoSuchPlanTask, catalog.ErrNoSuchTable},
+ {"no such table", errTypeNoSuchTable, catalog.ErrNoSuchTable, ErrNoSuchPlanTask},
+ {"no such namespace", errTypeNoSuchNamespace, catalog.ErrNoSuchNamespace, ErrNoSuchPlanTask},
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ idempotencyKey := "0190b6c5-1c3d-7000-8000-000000000003"
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchScanTasks}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/tasks", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodPost, req.Method)
+ writeRESTNotFound(t, w, tc.errType)
+ })
+ })
+
+ _, err := cat.FetchScanTasks(context.Background(), table.Identifier{"db", "tbl"}, FetchScanTasksRequest{
+ IdempotencyKey: &idempotencyKey,
+ PlanTask: "task-1",
+ })
+ require.ErrorIs(t, err, tc.wantErr)
+ if tc.notErr != nil {
+ assert.NotErrorIs(t, err, tc.notErr)
+ }
+ })
+ }
+}
+
+func TestPlanTableScanMapsNotFound(t *testing.T) {
+ t.Parallel()
+
+ // The POST .../plan 404 carries no plan-id, so a recognized 404 splits only
+ // into a gone table vs namespace; a bare or unrecognized 404 stays an
+ // ambiguous ErrRESTError rather than being guessed as a missing table.
+ cases := []struct {
+ name string
+ errType string // empty => bare 404 with no body
+ wantErr error
+ notErr error
+ }{
+ {"bare 404", "", ErrRESTError, catalog.ErrNoSuchTable},
+ {"unrecognized type", "SomeFutureException", ErrRESTError, catalog.ErrNoSuchTable},
+ {"no such table", errTypeNoSuchTable, catalog.ErrNoSuchTable, catalog.ErrNoSuchNamespace},
+ {"no such namespace", errTypeNoSuchNamespace, catalog.ErrNoSuchNamespace, catalog.ErrNoSuchTable},
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointPlanTableScan}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodPost, req.Method)
+ writeRESTNotFound(t, w, tc.errType)
+ })
+ })
+
+ _, err := cat.PlanTableScan(context.Background(), table.Identifier{"db", "tbl"}, PlanTableScanRequest{})
+ require.ErrorIs(t, err, tc.wantErr)
+ if tc.notErr != nil {
+ assert.NotErrorIs(t, err, tc.notErr)
+ }
+ })
+ }
+}
+
+func TestFetchPlanningResultResponseAcceptsCancelled(t *testing.T) {
+ t.Parallel()
+
+ // cancelled is a valid poll result (unlike PlanTableScanResponse, which
+ // rejects it). Pin it so a refactor routing it into the default error case
+ // is caught.
+ var resp FetchPlanningResultResponse
+ require.NoError(t, json.Unmarshal([]byte(`{"status":"cancelled"}`), &resp))
+ assert.Equal(t, PlanStatusCancelled, resp.Status)
+}
+
+func TestFetchPlanningResultStatusArms(t *testing.T) {
+ t.Parallel()
+
+ t.Run("cancelled returns ErrPlanCancelled", func(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+ _, err := w.Write([]byte(`{"status":"cancelled"}`))
+ require.NoError(t, err)
+ })
+ })
+
+ _, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+ require.ErrorIs(t, err, ErrPlanCancelled)
+ })
+
+ t.Run("failed returns PlanFailedError", func(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchPlanResult}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+ _, err := w.Write([]byte(`{"status":"failed","error":{"message":"boom","type":"ServerError","code":500}}`))
+ require.NoError(t, err)
+ })
+ })
+
+ _, err := cat.FetchPlanningResult(context.Background(), table.Identifier{"db", "tbl"}, "plan-123", FetchPlanningResultOptions{})
+ require.ErrorIs(t, err, ErrPlanFailed)
+ var pfe *PlanFailedError
+ require.ErrorAs(t, err, &pfe)
+ require.NotNil(t, pfe.Detail)
+ assert.Equal(t, "boom", pfe.Detail.Message)
+ })
+}
+
+func TestCancelPlanningRequest(t *testing.T) {
+ t.Parallel()
+
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointCancelPlanning}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/plan/plan-123", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodDelete, req.Method)
+ assert.Empty(t, req.Header.Values(headerIdempotencyKey))
+ assert.Empty(t, req.Header.Values(headerIcebergAccessDelegation))
+ w.WriteHeader(http.StatusNoContent)
+ })
+ })
+
+ require.NoError(t, cat.CancelPlanning(context.Background(), table.Identifier{"db", "tbl"}, "plan-123"))
+}
+
+func TestFetchScanTasksRequest(t *testing.T) {
+ t.Parallel()
+
+ idempotencyKey := "0190b6c5-1c3d-7000-8000-000000000002"
+ cat := newScanPlanningTestCatalog(t, []endpoint{endpointFetchScanTasks}, func(mux *http.ServeMux) {
+ mux.HandleFunc("/v1/namespaces/db/tables/tbl/tasks", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodPost, req.Method)
+ assert.Equal(t, idempotencyKey, req.Header.Get(headerIdempotencyKey))
+ assert.Empty(t, req.Header.Values(headerIcebergAccessDelegation))
+
+ body, err := io.ReadAll(req.Body)
+ require.NoError(t, err)
+ assert.JSONEq(t, `{"plan-task":"task-1"}`, string(body))
+
+ _, err = w.Write([]byte(`{
+ "plan-tasks": ["child-task"],
+ "file-scan-tasks": [{}],
+ "delete-files": [{}]
+ }`))
+ require.NoError(t, err)
+ })
+ })
+
+ resp, err := cat.FetchScanTasks(context.Background(), table.Identifier{"db", "tbl"}, FetchScanTasksRequest{
+ IdempotencyKey: &idempotencyKey,
+ PlanTask: "task-1",
+ })
+ require.NoError(t, err)
+ assert.Equal(t, []string{"child-task"}, resp.PlanTasks)
+ assert.Len(t, resp.FileScanTasks, 1)
+ assert.Len(t, resp.DeleteFiles, 1)
+}
+
+func TestScanPlanningEndpointGating(t *testing.T) {
+ t.Parallel()
+
+ ident := table.Identifier{"db", "tbl"}
+ cases := []struct {
+ name string
+ call func(*Catalog) error
+ }{
+ {"plan", func(c *Catalog) error {
+ _, err := c.PlanTableScan(context.Background(), ident, PlanTableScanRequest{})
+
+ return err
+ }},
+ {"fetch-result", func(c *Catalog) error {
+ _, err := c.FetchPlanningResult(context.Background(), ident, "plan-123", FetchPlanningResultOptions{})
+
+ return err
+ }},
+ {"cancel", func(c *Catalog) error {
+ return c.CancelPlanning(context.Background(), ident, "plan-123")
+ }},
+ {"fetch-tasks", func(c *Catalog) error {
+ _, err := c.FetchScanTasks(context.Background(), ident, FetchScanTasksRequest{PlanTask: "task-1"})
+
+ return err
+ }},
+ }
+
+ for _, tc := range cases {
+ t.Run(tc.name, func(t *testing.T) {
+ t.Parallel()
+
+ cat := &Catalog{endpoints: newEndpointSet(defaultEndpoints)}
+ err := tc.call(cat)
+ require.ErrorIs(t, err, ErrEndpointNotSupported)
+ assert.NotErrorIs(t, err, ErrRESTError)
+ })
+ }
+}
+
+func newScanPlanningTestCatalog(t *testing.T, endpoints []endpoint, register func(*http.ServeMux)) *Catalog {
+ t.Helper()
+
+ mux := http.NewServeMux()
+ mux.HandleFunc("/v1/config", func(w http.ResponseWriter, req *http.Request) {
+ require.Equal(t, http.MethodGet, req.Method)
+ err := json.NewEncoder(w).Encode(map[string]any{
+ "defaults": map[string]any{},
+ "overrides": map[string]any{},
+ "endpoints": endpointStrings(endpoints),
+ })
+ require.NoError(t, err)
+ })
+ if register != nil {
+ register(mux)
+ }
+
+ srv := httptest.NewServer(mux)
+ t.Cleanup(srv.Close)
+
+ cat, err := NewCatalog(context.Background(), "rest", srv.URL)
+ require.NoError(t, err)
+
+ return cat
+}
+
+func endpointStrings(endpoints []endpoint) []string {
+ if endpoints == nil {
+ return nil
+ }
+
+ out := make([]string, len(endpoints))
+ for i, e := range endpoints {
+ out[i] = e.String()
+ }
+
+ return out
+}
+
+// writeRESTNotFound writes a 404 response. A non-empty errType emits a REST
+// ErrorModel body ({"error":{...,"type":errType}}) so the client can split the
+// 404 on error.type; an empty errType writes a bare 404 with no body (the
+// fallback path).
+func writeRESTNotFound(t *testing.T, w http.ResponseWriter, errType string) {
+ t.Helper()
+
+ w.WriteHeader(http.StatusNotFound)
+ if errType == "" {
+ return
+ }
+
+ _, err := fmt.Fprintf(w, `{"error":{"message":%q,"type":%q,"code":404}}`, errType, errType)
+ require.NoError(t, err)
+}
+
+func stringPtr(s string) *string { return &s }