ID	IEP-129
Author	Maksim Timonin
Sponsor	Unknown User (nizhikov)
Created	10.09.2024
Status	ACTIVE

Motivation

Ignite provides a few options to set custom attributes on client side - per call (ServiceCallContext) or per connection (UserAttributes). But there is no opportunity to specify attributes on "application level". Scenario is:

Ignite connections from connection pool are used by different applications.
While processing data application need access to application attributes - an associative array of Strings specified on an application side. Business logic might depend on such attributes - application language, application name for audit, etc ([2], [4]).

It's proposed to provide such opportunity. Then there will be hierarchy of attributes:

Call level - ServiceCallContext
Application level - ApplicationAttributes
Connection level - UserAttributes, SecuritySubject

User defined functions might want access to different level of attributes. For example, SecuritySubject can be used to provide fine-grained access control to cache data. For example, CacheInterceptor saves the subject id it along with data and it can be used for fine-grained access control. Then it's proposed to introduce API that provides access to all this attributes while processing data in hierarchical order.

Requirements:

The attributes are explicitly set by application on Ignite API entry point (Ignite, IgniteClient, JDBC).
The attributes are fixed for every Ignite API call (can't be changed in the middle of the data processing).
The attributes must be accessible in stored functions on all nodes participated in requests and queries:
1. QuerySqlFunction
2. CacheInterceptor
3. Service
4. ComputeTask, ComputeJob

Attributes API that aren't part of the IEP:

ClientListenerConnectionContext#attributes - it's how client stores UserAttribute in connection context.
ComputeTaskSession#setAttribute - this mechanism is available only within Compute API. It allows attributes to be changed during task lifetime, use-case is different - send sync/async notifications between jobs about events happened during task lifetime.

Similar mechanisms in other DBMSs:

Application, Client contexts mechanisms exist in Oracle [1] and they are widely used [6].
Custom session variables exist in DBMS like SQLServer [8], Snowflake [7], MySQL [9].

Description

Setting application attributes

Ignite

Users set attributes with Ignite#withApplicationAttributes. It returns Ignite instance that is aware of the attributes.
Application attributes are propagated with all messages sent within operation on remote nodes (similar to GridIoSecurityAwareMessage)

// Example of usage.
try (Ignite ign = Ignition.start(ignCfg)) {
    Map<String, String> appAttrs = F.asMap("SESSION_ID", "1234");

	Ignite app = Ignite.withApplicationAttributes(appAttrs);	

 	...
}

IgniteClient (Java)

Users set attributes with IgniteClient#withApplicationAttributes.
New feature is needed in the ClientBitmaskFeature protocol.

// Example of usage.
try (IgniteClient cln = Ignition.startClient(clnCfg)) {
    Map<String, String> appAttrs = F.asMap("SESSION_ID", "1234");

	IgniteClient app = cln.withApplicationAttributes(appAttrs);	

 	...
}

JDBC

The standard jdbc protocol describes the methods Connection#setClientInfo, which allow changing the values of client attributes during the life of the connection [3]. Implementation features:

The list of attributes that can be set using #setClientInfo is arbitrary. The documentation recommends strictly limiting the set of attributes, but this is not necessary. For example, Oracle does not have such a limitation [5]. The setClientInfo array is completely translated into the getClientAttributes array.
The parameters set in setClientInfo are passed along with each JdbcRequest (this requires a new feature in JdbcThinFeature).
The client must reset the set values itself.

// JDBC connection to Ignite server.
try (Connection conn = DriverManager.getConnection(URL)) {
    conn.setClientInfo("SESSION_ID", "1234");
 
    ...
}

Accessing attributes

SessionContext is an entrypoint for accessing attributes on all levels and other session-level data (e.g. SecurutySubject).
User can easily create own QuerySqlFunction to get access to the attributes in SQL queries if needed (see example below).

Ignite provides SessionContextProviderResource to access to SessionContext. Provider instead of direct instance of the context is used for optimization. Injecting instance requires to have new instance of CacheInterceptor or QuerySqlFunction target class. It's not optimal to create new instances for every processing key or row.

Note, it proposes to make possible use non-static QuerySqlFunction to inject the resource.

/** SessionContext interface. It's an entrypoint for all attributes. */
public class SessionContext {
    /** @return Attribute by name. */
    public @Nullable String getAttribute(String attrName);

    /** @return Current SecuritySubject. */
	public @Nullable SecuritySubject getSecuritySubject();
 }
 
/** Example, use it in QuerySqlFunction. */
public static class UserDefinedFunctions {
    /** */
    @SessionContextProviderResource
    public SessionContextProvider sesCtxProv;

     /** @return Session ID set with application attributes. */
    @QuerySqlFunction
    public @Nullable String sessionId() {             
		SessionContext sesCtx = sesCtxProv.getSessionContext();

        return sesCtx == null ? null : sesCtx.getAttribute("SESSION_ID");
    }
}

Risks and Assumptions

No security checks are performed on the application attributes.
Application attributes keys and values are strings, to avoid serialization problems.
User should specify only few application attributes, and they should be small.
UserAttributes currently fill with node attributes (~50 items on node start), and they are not transferred between nodes. This process should be changed.