ref(etl-api): deprecate POST update-publication endpoint

[ttatsato]

What kind of change does this PR introduce?

Refactoring (API deprecation)

What is the current behavior?

POST /v1/sources/{source_id}/publications/{publication_name} performs a full replacement of the publication's table list, but using POST is semantically misleading — it implies an additive operation rather than a replacement.

Related issue: #459

What is the new behavior?

Marked the endpoint as deprecated in the OpenAPI summary and description
Added Deprecation: unix time (RFC 9745) and Link: <...>; rel="deprecation" (RFC 8288) response headers

A proper replacement endpoint is being designed. See #459.

Additional context

• No impact on existing clients
• Deprecation: 1778803200 (RFC 9745 sf-date) is used as a placeholder since the removal timeline is not yet determined.

How to test

BEFORE

# 1. Start Docker
./scripts/init.sh

# 2. Create tables
psql postgres://postgres:postgres@localhost:5430/postgres \
  -c "create table if not exists public.table_a(id int primary key, name text);"
psql postgres://postgres:postgres@localhost:5430/postgres \
  -c "create table if not exists public.table_b(id int primary key, name text);"

# 2.5 run a etl-API Server

cd ./crates/etl-api 
APP_ENVIRONMENT=dev cargo run

# 3. Create tenant/source
KEY='XOUbHmWbt9h7nWl15wWwyWQnctmFGNjpawMc3lT5CFs='
curl -X POST "http://127.0.0.1:8080/v1/tenants-sources" \
  -H "Authorization: Bearer $KEY" \
  -H "tenant_id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"my-tenant","tenant_name":"My Tenant","source_name":"Local Postgres",
       "source_config":{"host":"localhost","port":5430,"name":"postgres",
                        "username":"postgres","password":"postgres"}}'

# 4. Create a publication with table_a
curl -X POST "http://127.0.0.1:8080/v1/sources/1/publications" \
  -H "Authorization: Bearer $KEY" -H "tenant_id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"name":"test_pub","tables":[{"schema":"public","name":"table_a"}]}'

# 5. Call the deprecated endpoint to replace with table_b
#    Verify that the response includes: Deprecation: true
curl -v -X POST "http://127.0.0.1:8080/v1/sources/1/publications/test_pub" \
  -H "Authorization: Bearer $KEY" -H "tenant_id: my-tenant" \
  -H "Content-Type: application/json" \
  -d '{"tables":[{"schema":"public","name":"table_b"}]}'

# 6. Confirm table_a is replaced by table_b
curl -s "http://127.0.0.1:8080/v1/sources/1/publications" \
  -H "Authorization: Bearer $KEY" -H "tenant_id: my-tenant"
# → {"publications":[{"name":"test_pub","tables":[{"schema":"public","name":"table_b"}]}]}

AFTER

curl -i -X POST  http://127.0.0.1:8080/v1/sources/1/publications/test_pub \
-H "Authorization: Bearer $KEY" -H "tenant_id: my-tenant" \
-H "Content-Type: application/json" \
-d '{"tables":[{"schema":"public","name":"table_b"}]}'

# → HTTP/1.1 200 OK
# content-length: 0
# link: <https://github.com/supabase/etl/issues/459>; rel="deprecation"
# deprecation: @1778803200
# date: Fri, 15 May 2026 06:41:56 GMT

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 551ddf1378

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Use an RFC-compliant Deprecation header value

For clients that parse the standardized HTTP Deprecation field, this header will fail to parse because RFC 9745 defines it as an Item Structured Header whose value MUST be a date, e.g. @1688169599 (see https://www.ietf.org/rfc/rfc9745.html#section-2.1); true was only allowed by older drafts. Since this change adds the runtime deprecation signal for the endpoint, use an sf-date for the effective deprecation date, or omit Deprecation and rely on the Link header until a date is known.

Useful? React with 👍 / 👎.

[ttatsato]

fixed it 0c4eaeb