docs: Document custom header support for Table Topic REST catalogs

[aaron-seq]

Summary

This PR documents the existing custom header support for Table Topic REST catalog integrations, specifically addressing the Apache Polaris integration question raised in issue #2890.

Changes

Documentation

• Added concise documentation in docs/table-topic-custom-headers.md explaining:
  • How to configure custom HTTP headers for REST catalogs
  • Configuration pattern and examples
  • Reference to AutoMQ Labs repository for detailed integration examples

Addresses Code Review Feedback

• Removed redundant test case: Eliminated restWithPolarisRealmHeader() test as the existing restPassthroughProperties() test already validates custom header functionality
• Simplified documentation: Focused on core configuration pattern and pointed users to automq-labs repository for comprehensive integration examples
• Maintained backward compatibility: No code changes to core functionality

Key Features Documented

Configuration Pattern

automq.table.topic.catalog.header.{header-name}={header-value}

Example Usage

automq.table.topic.catalog.type=rest
automq.table.topic.catalog.uri=http://your-catalog-server:8181
automq.table.topic.catalog.header.Authorization=Bearer your-token
automq.table.topic.catalog.header.Polaris-Realm=your-realm-name

Addresses Issue

Closes #2890 by documenting that custom header support already exists in AutoMQ. The functionality has been working since it was implemented and is already tested via restPassthroughProperties(), but was not well-documented for users.

Testing

• Existing test restPassthroughProperties() validates header functionality
• All tests pass with the current implementation
• Removed duplicate test case to avoid redundancy

Compatibility

• No breaking changes - this is pure documentation
• No code changes to core functionality - documents existing features
• Backward compatible - existing configurations continue to work

Next Steps

Detailed integration examples including Apache Polaris setup, docker-compose configurations, and troubleshooting guides will be added to the AutoMQ Labs repository as suggested by the maintainers.

This PR ensures that users can easily discover the existing custom header functionality while keeping the main repository documentation focused and pointing to the appropriate location for comprehensive examples.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[Gezi-lzq]

Hi, @aaronseq12. Thank you for your contribution. However, as far as I know, there seems to be a similar test case targeting the same goal in the current codebase. Could you please clarify the differences and the necessity of your test case?

Also, thank you for the additional documentation on Apache Polaris integration. The repository at https://github.com/AutoMQ/automq-labs/tree/main/table-topic-solutions would be a more appropriate place for this. You are welcome to provide related integration and docker-compose examples there.

[aaron-seq]

Hi @Gezi-lzq, thank you for your feedback! Let me address your concerns:

Regarding the test case differences:

Yes, There is a similar test case restPassthroughProperties() that already tests custom header functionality. However, my new test case restWithPolarisRealmHeader() has some specific differences:

Existing test (restPassthroughProperties()):

• Tests a generic custom header (x-custom: my-x)
• Uses a simple RestCatalogMock that captures only the x-custom header
• General purpose header validation

New test (restWithPolarisRealmHeader()):

• Tests specific Apache Polaris headers (Polaris-Realm and Authorization)
• Uses RestCatalogMockForPolaris that specifically captures both Polaris headers
• Validates the exact Polaris integration scenario mentioned in issue [Question] Support for custom headers when integrating AutoMQ with Apache Polaris #2890
• Tests multiple headers simultaneously (realm + auth)

The new test serves as a concrete example for Polaris users and validates the specific use case that was requested. However, I understand your concern about the redundancy.

Regarding documentation location:

The automq-labs/table-topic-solutions repository would be more appropriate for integration examples and docker-compose setups.

Proposed changes:

1. Remove the duplicate test case to avoid redundancy
2. Move the documentation to automq-labs with practical examples
3. Keep only a minimal documentation update in the main repo pointing to the labs repository

Would you like me to update the PR with these changes? I can:

• Remove restWithPolarisRealmHeader() test and RestCatalogMockForPolaris class
• Create a comprehensive Polaris integration guide in automq-labs
• Update the main repo docs to just mention header support and point to the labs repo

What do you think?

[aaron-seq]

Updates added

I've updated the PR based on your feedback:

Changes Made:

1. Removed any redundant test case

   • Eliminated restWithPolarisRealmHeader() test method
   • Removed RestCatalogMockForPolaris class
   • The existing restPassthroughProperties() test already covers custom header functionality

2. Simplified documentation

   • Reduced documentation from 184 lines to ~50 lines
   • Focused on core configuration pattern
   • Added reference to AutoMQ Labs repository for detailed examples
   • Removed extensive troubleshooting and implementation details

3. Updated PR description

   • Reflected the simplified approach
   • Acknowledged the code review feedback
   • Clear next steps for comprehensive examples in automq-labs

Once this PR is merged, I'll create comprehensive Polaris integration examples with docker-compose setup in the automq-labs repository as you suggested.