feat: add restcatalog authentication api

Author: shuxu.li

src/iceberg/catalog/rest/CMakeLists.txt

@@ -15,7 +15,6 @@
 # specific language governing permissions and limitations
 # under the License.
 
-# Include auth subdirectory
 add_subdirectory(auth)
 
 set(ICEBERG_REST_SOURCES

src/iceberg/catalog/rest/auth/auth_manager.h

@@ -34,12 +34,23 @@
 namespace iceberg::rest::auth {
 
 /// \brief Produces authentication sessions for catalog and table requests.
+///
+/// AuthManager is responsible for creating authentication sessions at different scopes:
+/// - InitSession: Short-lived session for catalog initialization (optional)
+/// - CatalogSession: Long-lived session for catalog-level operations (required)
+/// - TableSession: Optional table-specific session or reuse of catalog session
+///
+/// Implementations are registered via AuthManagers::Register() and loaded by auth type.
 class ICEBERG_REST_EXPORT AuthManager {
  public:
   virtual ~AuthManager() = default;
 
   /// \brief Create a short-lived session used to contact the configuration endpoint.
   ///
+  /// This session is used only during catalog initialization to fetch server
+  /// configuration and perform initial authentication. It is typically discarded after
+  /// initialization.
+  ///
   /// \param init_client HTTP client used for initialization requests.
   /// \param properties Client configuration supplied by the catalog.
   /// \return Session for initialization or an error if credentials cannot be acquired.
@@ -49,6 +60,10 @@ class ICEBERG_REST_EXPORT AuthManager {
 
   /// \brief Create the long-lived catalog session that acts as the parent session.
   ///
+  /// This session is used for all catalog-level operations (list namespaces, list tables,
+  /// etc.) and serves as the parent session for table-specific operations. It is owned
+  /// by the catalog and reused throughout the catalog's lifetime.
+  ///
   /// \param shared_client HTTP client owned by the catalog and reused for auth calls.
   /// \param properties Catalog properties (client config + server defaults).
   /// \return Session for catalog operations or an error if authentication cannot be set
@@ -64,8 +79,8 @@ class ICEBERG_REST_EXPORT AuthManager {
   ///
   /// \param table Target table identifier.
   /// \param properties Table-specific auth properties returned by the server.
-  /// \param parent Catalog session to read information from.
-  /// \return A new session for the table, nullptr to reuse parent, or an error.
+  /// \param parent Catalog session to inherit from or extract information from.
+  /// \return A new session for the table, nullptr to reuse parent session, or an error.
   virtual Result<std::unique_ptr<AuthSession>> TableSession(
       const TableIdentifier& table,
       const std::unordered_map<std::string, std::string>& properties,

src/iceberg/catalog/rest/auth/auth_session.h

@@ -64,10 +64,8 @@ class ICEBERG_REST_EXPORT AuthSession {
   /// sessions (e.g., OAuth2 with token refresh), this should stop any background
   /// threads and release resources.
   ///
-  /// Note: Since sessions may be cached, this method may not be called immediately
-  /// after the session is no longer needed, but rather when the session is evicted
-  /// from the cache or the cache itself is closed.
-  virtual void Close() {}
+  /// \return Status indicating success or failure of closing the session.
+  virtual Status Close() { return {}; }
 };
 
 /// \brief A default authentication session that adds static headers to requests.