Motivation

When processing data, users want to have access to non-tabular (not stored in cache structures) data. Example of such data is application attributes - an associative array specified on an application side. Usage scenarios:

1. To run certain logic that depends on the value of the attribute (for example, the application language [2], progress monitoring [4]).
2. To audit changes in the database (for example, CacheInterceptor extracts the user from the attributes and saves it along with data).
3. To optimize the transfer of parameters to processing functions (for example, multiple QuerySqlFunction use the same parameter and it is convenient to take it from the attributes, rather than transfer it separately to each function).

Another examples of non-tabular data that can be accessed are SecuritySubject, UserAttributes and current Transaction.

The requirements include:

1. Attributes must be accessible from user defined functions (QuerySqlFunction, CacheInterceptor).
2. Setting attributes via protocols: thin client, jdbc:thin.
3. Attribute values ​​can change during the life of the connection (a connection from a connection pool can be sequentially used by different applications).

Ignite does not have a similar public API:

1. ServiceCallContext helps solve similar problems, but has several limitations. The main one is that it is only available in calls via the IgniteService API and cannot be used for single operations or transactions.
2. UserAttributes - allows to set user attributes, but the attribute values ​​are fixed for the entire lifetime of the connection.

A similar context mechanism exists in Oracle [1] and it's widely used. 

Description

Accessing attributes

1. ApplicationContext is an entrypoint for accessing all non-tabular data.
2. Access requires static methods, because objects injection isn't possible for user functions (QuerySqlFunction are static, CacheInterceptor is a singleton for cache).

/** ApplicationContext interface. It's an entrypoint for all non-tabular information. */
public class ApplicationContext {
    /** @return Application attributes set for current thread. */
    public static @Nullable Map<String, String> getAttributes();
 }
 
/** Example, use it in QuerySqlFunction. */
public static class UserDefinedFunctions {
    /** @return Session ID, application attribute. */
    @QuerySqlFunction
    public static String sessionId() {
        Map<String, String> appAttrs = ApplicationContext.getAttributes();
 
        return appAttrs == null ? null : appAttr.get(SESSION_ID);
    }
}

Setting attributes

Ignite 

1. Ignite doesn't have support an abstraction "session". It also doesn't restrict usage on Ignite instance from multiple threads by different applications. Also the same thread can be shared between multiple applications.
2. The application attributes might be used in SQL, Cache API. The ApplicationContext should not depend on the used API.
3. Then minimal unit of interaction between application and Ignite is a transaction. I suggest to attach the attributes to a transaction.

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

1. Application acquires Ignite connect from connection pool.
2. Application need specify ApplicationAttributes. Business logic might depend on such attributes - application language, application name for audit, etc ([2], [4]).
3. Another application re-uses this connect with own attributes values.

It's proposed to provide the opportunity to set attributes for application. Then there will be hierarchy of attributes:

1. Call level - ServiceCallContext
2. Application level - ApplicationAttributes
3. Connection level - UserAttributes, SecuritySubject

The access to the attributes must be provided for functions that are pre-created on Ignite cluster and aren't deployed by specific application. Examples:

• CacheInterceptor saves the SecuritySubject along with data and it can be used for fine-grained access control in QuerySqlFunction.
• Service extracts attribute from ServiceCallContext and, if absent, get default one from ApplicationAttributes.

It's proposed to introduce SessionContext API that is available from the functions and provides access to the attributes in order (call, application, connection).

Requirements:

1. The attributes ​​are set by application only once for Ignite API entry point (Ignite, IgniteClient, JDBC).
2. The attributes are available on all participating nodes of the application requests and queries.
3. The attributes must be accessible in pre-defined functions:
   1. QuerySqlFunction
   2. CacheInterceptor
   3. Service
   4. ComputeTask, ComputeJob

Attributes API that aren't part of the IEP:

1. ClientListenerConnectionContext#attributes - it's actually how client stores UserAttribute in connection context.
2. 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:

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

Description

Setting application attributes

Ignite 

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

// 

// Extends the interface with new public method.
public interface IgniteTransactions {
 	...

    /** @param appAttrs Application attributes. */
    public IgniteTransactions withApplicationAttributes(Map<String, String> appAttrs);
}

// Example of usage.
try (Ignite ign = Ignition.localIgnitestart(ignCfg)) {
     Map<String, String> appAttrs = F.asMap("SESSION_ID", "1234");
 
	Ignite     try (Transaction tx app = ignIgnite.transactions().withApplicationAttributes(appAttrs).txStart()) { 
        ;	

 	...
    }
}

IgniteClient (Java)

...

1. Users set attributes with IgniteClient#withApplicationAttributesClient should mirror the logic of Ignite node.
2. New feature is needed in the ClientBitmaskFeature protocol.

// Extends the interface with new public method.
public interface ClientTransactions {
	...

    /** @param appAttrs Application attributes. */
    public ClientTransactions withApplicationAttributes(Map<String, String> appAttrs);
}

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

	IgniteClient    try (ClientTransaction tx app = cln.transactions().withApplicationAttributes(appAttrs).txStart()) {
        ;	

 	...
    }
}

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:

1. 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 ApplicationAttributes.
2. The parameters set in setClientInfo are passed along with each JdbcRequest (this requires a new feature in JdbcThinFeature).
3. The client must reset the set values ​​itself.

...

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

Spreading context across cluster nodes

1. Via the QueryStartRequest SQL message protocol (for jdbc, SQL transactions)
2. Via the transaction protocol for handling inserts (CacheInterceptor), since inserts are not always performed on the request initiator node.

Risks and Assumptions

// Describe project risks, such as API or binary compatibility issues, major protocol changes, etc.

1. It doesn't work for non-transactional ignite-node SQL but work for JDBC.

Discussion Links

Accessing attributes

SessionContext is an entrypoint for accessing attributes on all levels and other session-level data (e.g. SecurutySubject). Ignite provides SessionContextProviderResource to access to SessionContext.

1. Injecting the ProviderResource doesn't require new instance of CacheInterceptor or QuerySqlFunction target class for every call (every row or key).
2. Provider implementation is responsible for extracting SessionContext from Ignite thread.
3. 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 {
    /** Injection performs once per query. */
    @SessionContextProviderResource
    public SessionContextProvider sesCtxProv;

    /** @return Session ID set with application attributes. */
    @QuerySqlFunction
    public @Nullable String sessionId() {             
		return sesCtxProv.getSessionContext().getAttribute("SESSION_ID");
    }
}

Risks and Assumptions

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

Discussion Links

https://lists.apache.org/thread/c5j5yykr6tfrnp9zprhg9j69w63r11zx// Links to discussions on the devlist, if applicable.

Reference Links

[1] https://docs.oracle.com/en/database/oracle/oracle-database/19/dbseg/using-application-contexts-to-retrieve-user-information.html#GUID-51C9D5FA-6787-4F05-82EF-A5968BEDC5A0

...

[5] https://docs.oracle.com/database/121/JJDBC/jdbcvers.htm#BABDAEEC

Tickets

[6] https://stackoverflow.com/search?tab=newest&q=SYS_CONTEXT

[7] https://docs.snowflake.com/en/sql-reference/session-variables#session-variable-functions

[8] https://learn.microsoft.com/en-us/sql/t-sql/functions/session-context-transact-sql?view=sql-server-ver16

[9] https://dev.mysql.com/doc/refman/8.4/en/user-variables.html

Tickets