From 6accbf51a64f4c3ecaf2ff2e610b42f32e0b420a Mon Sep 17 00:00:00 2001 From: Serge Klochkov <3175289+slvrtrn@users.noreply.github.com> Date: Wed, 6 Nov 2024 16:11:39 +0100 Subject: [PATCH] Role query parameters (#351) Co-authored-by: Andrew Davis --- CHANGELOG.md | 6 + examples/README.md | 1 + examples/role.ts | 129 ++++++++ .../integration/exec_and_command.test.ts | 8 +- .../__tests__/integration/role.test.ts | 311 ++++++++++++++++++ .../__tests__/unit/to_search_params.test.ts | 20 ++ .../client-common/__tests__/utils/jasmine.ts | 8 + packages/client-common/src/client.ts | 8 + packages/client-common/src/config.ts | 3 + packages/client-common/src/connection.ts | 1 + packages/client-common/src/utils/url.ts | 12 + .../src/connection/node_base_connection.ts | 3 + .../src/connection/web_connection.ts | 3 + 13 files changed, 507 insertions(+), 6 deletions(-) create mode 100644 examples/role.ts create mode 100644 packages/client-common/__tests__/integration/role.test.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 1ef56960..a2203b42 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,9 @@ +# 1.8.0 (Common, Node.js, Web) + +## New features + +- Added support for specifying roles via request query parameters. See [this example](examples/role.ts) for more details. ([@pulpdrew](https://github.com/pulpdrew), [#328](https://github.com/ClickHouse/clickhouse-js/pull/328)) + # 1.7.0 (Common, Node.js, Web) ## Bug fixes diff --git a/examples/README.md b/examples/README.md index 225eff8a..b98afa6a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -68,6 +68,7 @@ If something is missing, or you found a mistake in one of these examples, please - [default_format_setting.ts](default_format_setting.ts) - sending queries using `exec` method without a `FORMAT` clause; the default format will be set from the client settings. - [session_id_and_temporary_tables.ts](session_id_and_temporary_tables.ts) - creating a temporary table, which requires a session_id to be passed to the server. - [session_level_commands.ts](session_level_commands.ts) - using SET commands, memorized for the specific session_id. +- [role.ts](role.ts) - using one or more roles without explicit `USE` commands or session IDs ## How to run diff --git a/examples/role.ts b/examples/role.ts new file mode 100644 index 00000000..176aafed --- /dev/null +++ b/examples/role.ts @@ -0,0 +1,129 @@ +import type { ClickHouseError } from '@clickhouse/client' +import { createClient } from '@clickhouse/client' // or '@clickhouse/client-web' + +/** + * An example of specifying a role using query parameters + * See https://clickhouse.com/docs/en/interfaces/http#setting-role-with-query-parameters + */ +void (async () => { + const format = 'JSONEachRow' + const username = 'clickhouse_js_role_user' + const password = 'role_user_password' + const table1 = 'clickhouse_js_role_table_1' + const table2 = 'clickhouse_js_role_table_2' + + // Create 2 tables, a role for each table allowing SELECT, and a user with access to those roles + const defaultClient = createClient() + await createOrReplaceUser(username, password) + const table1Role = await createTableAndGrantAccess(table1, username) + const table2Role = await createTableAndGrantAccess(table2, username) + await defaultClient.close() + + // Create a client using a role that only has permission to query table1 + const client = createClient({ + username, + password, + // This role will be applied to all the queries by default, + // unless it is overridden in a specific method call + role: table1Role, + }) + + // Selecting from table1 is allowed using table1Role + const resultSet1 = await client.query({ + query: `select count(*) from ${table1}`, + format, + }) + console.log( + `Successfully queried from ${table1} using ${table1Role}. Result: `, + await resultSet1.json(), + ) + + // Selecting from table2 is not allowed using table1Role, + // which is set by default in the client instance + await client + .query({ query: `select count(*) from ${table2}`, format }) + .catch((e: ClickHouseError) => { + console.error( + `Failed to query from ${table2}, as ${table1Role} does not have sufficient privileges. Expected error:`, + e, + ) + }) + + // Override the client's role to table2Role, allowing a query to table2 + const resultSet2 = await client.query({ + query: `select count(*) from ${table2}`, + role: table2Role, + format, + }) + console.log( + `Successfully queried from ${table2} using ${table2Role}. Result:`, + await resultSet2.json(), + ) + + // Selecting from table1 is no longer allowed, since table2Role is being used + await client + .query({ + query: `select count(*) from ${table1}`, + role: table2Role, + format, + }) + .catch((e: ClickHouseError) => { + console.error( + `Failed to query from ${table1}, as ${table2Role} does not have sufficient privileges. Expected error:`, + e, + ) + }) + + // Multiple roles can be specified to allowed querying from either table + const resultSet3 = await client.query({ + query: `select count(*) from ${table1}`, + role: [table1Role, table2Role], + format, + }) + console.log( + `Successfully queried from ${table1} using roles: [${table1Role}, ${table2Role}]. Result:`, + await resultSet3.json(), + ) + + const resultSet4 = await client.query({ + query: `select count(*) from ${table2}`, + role: [table1Role, table2Role], + format, + }) + console.log( + `Successfully queried from ${table2} using roles: [${table1Role}, ${table2Role}]. Result: `, + await resultSet4.json(), + ) + + await client.close() + + async function createOrReplaceUser(username: string, password: string) { + await defaultClient.command({ + query: `CREATE USER OR REPLACE ${username} IDENTIFIED WITH plaintext_password BY '${password}'`, + }) + } + + async function createTableAndGrantAccess( + tableName: string, + username: string, + ) { + const role = `${tableName}_role` + + await defaultClient.command({ + query: ` + CREATE OR REPLACE TABLE ${tableName} + (id UInt32, name String, sku Array(UInt32)) + ENGINE MergeTree() + ORDER BY (id) + `, + }) + + await defaultClient.command({ query: `CREATE ROLE OR REPLACE ${role}` }) + await defaultClient.command({ + query: `GRANT SELECT ON ${tableName} TO ${role}`, + }) + await defaultClient.command({ query: `GRANT ${role} TO ${username}` }) + + return role + } +})() diff --git a/packages/client-common/__tests__/integration/exec_and_command.test.ts b/packages/client-common/__tests__/integration/exec_and_command.test.ts index f8e46c3c..64e25c3d 100644 --- a/packages/client-common/__tests__/integration/exec_and_command.test.ts +++ b/packages/client-common/__tests__/integration/exec_and_command.test.ts @@ -3,7 +3,6 @@ import { type ClickHouseClient } from '@clickhouse/client-common' import { createTestClient, getClickHouseTestEnvironment, - getTestDatabaseName, guid, TestEnv, validateUUID, @@ -51,8 +50,8 @@ describe('exec and command', () => { }) }) - it('does not swallow ClickHouse error', async () => { - const { ddl, tableName } = getDDL() + it('should not swallow ClickHouse error', async () => { + const { ddl } = getDDL() const commands = async () => { const command = () => runExec({ @@ -65,9 +64,6 @@ describe('exec and command', () => { jasmine.objectContaining({ code: '57', type: 'TABLE_ALREADY_EXISTS', - message: jasmine.stringContaining( - `Table ${getTestDatabaseName()}.${tableName} already exists. `, - ), }), ) }) diff --git a/packages/client-common/__tests__/integration/role.test.ts b/packages/client-common/__tests__/integration/role.test.ts new file mode 100644 index 00000000..8534bdf3 --- /dev/null +++ b/packages/client-common/__tests__/integration/role.test.ts @@ -0,0 +1,311 @@ +import type { ClickHouseClient } from '@clickhouse/client-common' +import { createTestClient, TestEnv, whenOnEnv } from '@test/utils' +import { createSimpleTable } from '../fixtures/simple_table' +import { assertJsonValues, jsonValues } from '../fixtures/test_data' +import { getTestDatabaseName, guid } from '../utils' + +whenOnEnv(TestEnv.LocalSingleNode).describe('role settings', () => { + let defaultClient: ClickHouseClient + let client: ClickHouseClient + + let database: string + let username: string + let password: string + let roleName1: string + let roleName2: string + + beforeAll(async () => { + defaultClient = createTestClient() + username = `clickhousejs__user_with_roles_${guid()}` + password = `CHJS_${guid()}` + roleName1 = `TEST_ROLE_${guid()}` + roleName2 = `TEST_ROLE_${guid()}` + database = getTestDatabaseName() + + await defaultClient.command({ + query: `CREATE USER ${username} IDENTIFIED WITH sha256_password BY '${password}' DEFAULT DATABASE ${database}`, + }) + await defaultClient.command({ + query: `CREATE ROLE IF NOT EXISTS ${roleName1}`, + }) + await defaultClient.command({ + query: `CREATE ROLE IF NOT EXISTS ${roleName2}`, + }) + await defaultClient.command({ + query: `GRANT ${roleName1}, ${roleName2} TO ${username}`, + }) + await defaultClient.command({ + query: `GRANT INSERT ON ${database}.* TO ${roleName1}`, + }) + await defaultClient.command({ + query: `GRANT CREATE TABLE ON * TO ${roleName1}`, + }) + }) + + afterEach(async () => { + await client.close() + }) + + afterAll(async () => { + await defaultClient.close() + }) + + describe('for queries', () => { + async function queryCurrentRoles(role?: string | Array) { + const rs = await client.query({ + query: 'select currentRoles() as roles', + format: 'JSONEachRow', + role, + }) + + const jsonResults = (await rs.json()) as { roles: string[] }[] + return jsonResults[0].roles + } + + it('should use a single role from the client configuration', async () => { + client = createTestClient({ + username, + password, + role: roleName1, + }) + + const actualRoles = await queryCurrentRoles() + expect(actualRoles).toEqual([roleName1]) + }) + + it('should use multiple roles from the client configuration', async () => { + client = createTestClient({ + username, + password, + role: [roleName1, roleName2], + }) + + const actualRoles = await queryCurrentRoles() + expect(actualRoles.length).toBe(2) + expect(actualRoles).toContain(roleName1) + expect(actualRoles).toContain(roleName2) + }) + + it('should use single role from the query options', async () => { + client = createTestClient({ + username, + password, + role: [roleName1, roleName2], + }) + + const actualRoles = await queryCurrentRoles(roleName2) + expect(actualRoles).toEqual([roleName2]) + }) + + it('should use multiple roles from the query options', async () => { + client = createTestClient({ + username, + password, + }) + + const actualRoles = await queryCurrentRoles([roleName1, roleName2]) + expect(actualRoles.length).toBe(2) + expect(actualRoles).toContain(roleName1) + expect(actualRoles).toContain(roleName2) + }) + }) + + describe('for inserts', () => { + let tableName: string + + beforeEach(async () => { + tableName = `role_insert_test_${guid()}` + await createSimpleTable(defaultClient, tableName) + }) + + async function tryInsert(role?: string | Array) { + await client.insert({ + table: tableName, + values: jsonValues, + format: 'JSONEachRow', + role, + }) + } + + it('should successfully insert when client specifies a role that is allowed to insert', async () => { + client = createTestClient({ + username, + password, + role: roleName1, + }) + + await tryInsert() + await assertJsonValues(defaultClient, tableName) + }) + + it('should successfully insert when client specifies multiple roles and at least one is allowed to insert', async () => { + client = createTestClient({ + username, + password, + role: [roleName1, roleName2], + }) + + await tryInsert() + await assertJsonValues(defaultClient, tableName) + }) + + it('should fail to insert when client specifies a role that is not allowed to insert', async () => { + client = createTestClient({ + username, + password, + role: roleName2, + }) + + await expectAsync(tryInsert()).toBeRejectedWith( + jasmine.objectContaining({ + message: jasmine.stringContaining('Not enough privileges'), + code: '497', + type: 'ACCESS_DENIED', + }), + ) + }) + + it('should successfully insert when insert specifies a role that is allowed to insert', async () => { + client = createTestClient({ + username, + password, + role: roleName2, + }) + + await tryInsert(roleName1) + await assertJsonValues(defaultClient, tableName) + }) + + it('should successfully insert when insert specifies multiple roles and at least one is allowed to insert', async () => { + client = createTestClient({ + username, + password, + role: roleName2, + }) + + await tryInsert([roleName1, roleName2]) + await assertJsonValues(defaultClient, tableName) + }) + + it('should fail to insert when insert specifies a role that is not allowed to insert', async () => { + client = createTestClient({ + username, + password, + role: roleName1, + }) + + await expectAsync(tryInsert(roleName2)).toBeRejectedWith( + jasmine.objectContaining({ + message: jasmine.stringContaining('Not enough privileges'), + code: '497', + type: 'ACCESS_DENIED', + }), + ) + }) + }) + + describe('for commands', () => { + let tableName: string + + beforeEach(async () => { + tableName = `role_command_test_${guid()}` + }) + + async function tryCreateTable(role?: string | Array) { + const query = ` + CREATE TABLE ${tableName} + (id UInt64, name String, sku Array(UInt8), timestamp DateTime) + ENGINE = MergeTree() + ORDER BY (id) + ` + await client.command({ query, role }) + } + + async function checkCreatedTable(tableName: string) { + const selectResult = await defaultClient.query({ + query: `SELECT * from system.tables where name = '${tableName}'`, + format: 'JSON', + }) + + const { data, rows } = await selectResult.json<{ name: string }>() + expect(rows).toBe(1) + expect(data[0].name).toBe(tableName) + } + + it('should successfully create a table when client specifies a role that is allowed to create tables', async () => { + client = createTestClient({ + username, + password, + role: roleName1, + }) + + await tryCreateTable() + await checkCreatedTable(tableName) + }) + + it('should successfully create table when client specifies multiple roles and at least one is allowed to create tables', async () => { + client = createTestClient({ + username, + password, + role: [roleName1, roleName2], + }) + + await tryCreateTable() + await checkCreatedTable(tableName) + }) + + it('should fail to create a table when client specifies a role that is not allowed to create tables', async () => { + client = createTestClient({ + username, + password, + role: roleName2, + }) + + await expectAsync(tryCreateTable()).toBeRejectedWith( + jasmine.objectContaining({ + message: jasmine.stringContaining('Not enough privileges'), + code: '497', + type: 'ACCESS_DENIED', + }), + ) + }) + + it('should successfully create table when command specifies a role that is allowed to create tables', async () => { + client = createTestClient({ + username, + password, + role: roleName2, + }) + + await tryCreateTable(roleName1) + await checkCreatedTable(tableName) + }) + + it('should successfully create table when command specifies multiple roles and at least one is allowed to create tables', async () => { + client = createTestClient({ + username, + password, + role: roleName2, + }) + + await tryCreateTable([roleName1, roleName2]) + await checkCreatedTable(tableName) + }) + + it('should fail to create table when command specifies a role that is not allowed to create tables', async () => { + client = createTestClient({ + username, + password, + role: roleName1, + }) + + await expectAsync(tryCreateTable(roleName2)).toBeRejectedWith( + jasmine.objectContaining({ + message: jasmine.stringContaining('Not enough privileges'), + code: '497', + type: 'ACCESS_DENIED', + }), + ) + }) + }) +}) diff --git a/packages/client-common/__tests__/unit/to_search_params.test.ts b/packages/client-common/__tests__/unit/to_search_params.test.ts index 3f6f43ea..f5076701 100644 --- a/packages/client-common/__tests__/unit/to_search_params.test.ts +++ b/packages/client-common/__tests__/unit/to_search_params.test.ts @@ -78,6 +78,7 @@ describe('toSearchParams', () => { qaz: 'qux', }, session_id: 'my-session-id', + role: ['my-role-1', 'my-role-2'], query_id: 'my-query-id', query, })! @@ -89,10 +90,29 @@ describe('toSearchParams', () => { ['param_qaz', 'qux'], ['query', 'SELECT * FROM system.query_log'], ['query_id', 'my-query-id'], + ['role', 'my-role-1'], + ['role', 'my-role-2'], ['session_id', 'my-session-id'], ['wait_end_of_query', '1'], ]) }) + + it('should set a single role', async () => { + const query = 'SELECT * FROM system.query_log' + const params = toSearchParams({ + query, + database: 'some_db', + query_id: 'my-query-id', + role: 'single-role', + })! + const result = toSortedArray(params) + expect(result).toEqual([ + ['database', 'some_db'], + ['query', 'SELECT * FROM system.query_log'], + ['query_id', 'my-query-id'], + ['role', 'single-role'], + ]) + }) }) function toSortedArray(params: URLSearchParams): [string, string][] { diff --git a/packages/client-common/__tests__/utils/jasmine.ts b/packages/client-common/__tests__/utils/jasmine.ts index d6023bf0..907ee3fc 100644 --- a/packages/client-common/__tests__/utils/jasmine.ts +++ b/packages/client-common/__tests__/utils/jasmine.ts @@ -8,10 +8,18 @@ export const whenOnEnv = (...envs: TestEnv[]) => { envs.includes(currentEnv) ? it(...args) : logItAndSkip(currentEnv, ...args), + fit: (...args: Parameters) => + envs.includes(currentEnv) + ? fit(...args) + : logItAndSkip(currentEnv, ...args), describe: (...args: Parameters) => envs.includes(currentEnv) ? describe(...args) : logDescribeAndSkip(currentEnv, ...args), + fdescribe: (...args: Parameters) => + envs.includes(currentEnv) + ? fdescribe(...args) + : logDescribeAndSkip(currentEnv, ...args), } } diff --git a/packages/client-common/src/client.ts b/packages/client-common/src/client.ts index d7039b00..83481b12 100644 --- a/packages/client-common/src/client.ts +++ b/packages/client-common/src/client.ts @@ -31,6 +31,10 @@ export interface BaseQueryParams { * If it is not set, {@link BaseClickHouseClientConfigOptions.session_id} will be used. * @default undefined (no override) */ session_id?: string + /** A specific list of roles to use for this query. + * If it is not set, {@link BaseClickHouseClientConfigOptions.roles} will be used. + * @default undefined (no override) */ + role?: string | Array /** When defined, overrides the credentials from the {@link BaseClickHouseClientConfigOptions.username} * and {@link BaseClickHouseClientConfigOptions.password} settings for this particular request. * @default undefined (no override) */ @@ -151,6 +155,7 @@ export class ClickHouseClient { private readonly makeResultSet: MakeResultSet private readonly valuesEncoder: ValuesEncoder private readonly sessionId?: string + private readonly role?: string | Array private readonly logWriter: LogWriter constructor( @@ -168,6 +173,7 @@ export class ClickHouseClient { this.logWriter = this.connectionParams.log_writer this.clientClickHouseSettings = this.connectionParams.clickhouse_settings this.sessionId = config.session_id + this.role = config.role this.connection = config.impl.make_connection( configWithURL, this.connectionParams, @@ -205,6 +211,7 @@ export class ClickHouseClient { message: 'Error while processing the ResultSet.', args: { session_id: queryParams.session_id, + role: queryParams.role, query, query_id, }, @@ -306,6 +313,7 @@ export class ClickHouseClient { abort_signal: params.abort_signal, query_id: params.query_id, session_id: params.session_id ?? this.sessionId, + role: params.role ?? this.role, auth: params.auth, } } diff --git a/packages/client-common/src/config.ts b/packages/client-common/src/config.ts index e29871e3..b2bd013a 100644 --- a/packages/client-common/src/config.ts +++ b/packages/client-common/src/config.ts @@ -64,6 +64,9 @@ export interface BaseClickHouseClientConfigOptions { /** ClickHouse Session id to attach to the outgoing requests. * @default empty string (no session) */ session_id?: string + /** ClickHouse role name(s) to attach to the outgoing requests. + * @default undefined string (no roles) */ + role?: string | Array /** @deprecated since version 1.0.0. Use {@link http_headers} instead.
* Additional HTTP headers to attach to the outgoing requests. * @default empty object */ diff --git a/packages/client-common/src/connection.ts b/packages/client-common/src/connection.ts index 821fe1b1..19090d96 100644 --- a/packages/client-common/src/connection.ts +++ b/packages/client-common/src/connection.ts @@ -33,6 +33,7 @@ export interface ConnBaseQueryParams { session_id?: string query_id?: string auth?: { username: string; password: string } + role?: string | Array } export interface ConnInsertParams extends ConnBaseQueryParams { diff --git a/packages/client-common/src/utils/url.ts b/packages/client-common/src/utils/url.ts index 0963aeb9..690ee625 100644 --- a/packages/client-common/src/utils/url.ts +++ b/packages/client-common/src/utils/url.ts @@ -37,6 +37,7 @@ type ToSearchParamsOptions = { query?: string session_id?: string query_id: string + role?: string | Array } // TODO validate max length of the resulting query @@ -48,6 +49,7 @@ export function toSearchParams({ clickhouse_settings, session_id, query_id, + role, }: ToSearchParamsOptions): URLSearchParams { const params = new URLSearchParams() params.set('query_id', query_id) @@ -78,5 +80,15 @@ export function toSearchParams({ params.set('session_id', session_id) } + if (role) { + if (typeof role === 'string') { + params.set('role', role) + } else if (Array.isArray(role)) { + for (const r of role) { + params.append('role', r) + } + } + } + return params } diff --git a/packages/client-node/src/connection/node_base_connection.ts b/packages/client-node/src/connection/node_base_connection.ts index 5c4b1ec3..d17dfc84 100644 --- a/packages/client-node/src/connection/node_base_connection.ts +++ b/packages/client-node/src/connection/node_base_connection.ts @@ -141,6 +141,7 @@ export abstract class NodeBaseConnection session_id: params.session_id, clickhouse_settings, query_id, + role: params.role, }) const { controller, controllerCleanup } = this.getAbortController(params) // allows to enforce the compression via the settings even if the client instance has it disabled @@ -192,6 +193,7 @@ export abstract class NodeBaseConnection query_params: params.query_params, query: params.query, session_id: params.session_id, + role: params.role, query_id, }) const { controller, controllerCleanup } = this.getAbortController(params) @@ -382,6 +384,7 @@ export abstract class NodeBaseConnection database: this.params.database, query_params: params.query_params, session_id: params.session_id, + role: params.role, clickhouse_settings, query_id, } diff --git a/packages/client-web/src/connection/web_connection.ts b/packages/client-web/src/connection/web_connection.ts index 72c69ea5..493d9e19 100644 --- a/packages/client-web/src/connection/web_connection.ts +++ b/packages/client-web/src/connection/web_connection.ts @@ -50,6 +50,7 @@ export class WebConnection implements Connection { clickhouse_settings, query_params: params.query_params, session_id: params.session_id, + role: params.role, query_id, }) const response = await this.request({ @@ -93,6 +94,7 @@ export class WebConnection implements Connection { query_params: params.query_params, query: params.query, session_id: params.session_id, + role: params.role, query_id, }) const response = await this.request({ @@ -224,6 +226,7 @@ export class WebConnection implements Connection { clickhouse_settings: params.clickhouse_settings, query_params: params.query_params, session_id: params.session_id, + role: params.role, query_id, }) const response = await this.request({