Users Package

About this project

Project Description

This Python module is designed to simplify user management in Telegram Bots by providing necessary functionality such as: authentication, authorization and request limitation, providing efficient management of user attributes and access rights.

Interaction Model 1: Using a Unified Entrypoint (Method: user_access_check())

sequenceDiagram
    participant Bot
    participant Users-Module
    Bot->>Users-Module: Create Users-Module instance with rate limits
    Bot->>Users-Module: Call user_access_check(user_id, role_id)
    Users-Module-->>Bot: Return access, permissions, and rate limits

Loading

Key Features

This module is designed primarily for Telegram bots but can be adapted for various projects that require user management, role-based access control, and request rate limiting.
This module requires certain dependencies related to
- Vault
  - Vault Server for storing user configurations and historical data
  - Additional Module to interact with the Vault API
  - Vault Policy with access rights to the Vault Server
- PostgreSQL
  - PostgreSQL Server for storing user data and historical records
  - PostgreSQL Schema for creating tables in the database

Description of module Constants

This module contains constant values

Constant Name	Description	Default Value
`USERS_VAULT_CONFIG_PATH`	Path for configuration data in Vault.	`"configuration/users"`
`USER_STATUS_ALLOW`	User access status for allowed access.	`"allowed"`
`USER_STATUS_DENY`	User access status for denied access.	`"denied"`

Description of module Exceptions

Exception	Describe	Tips
`WrongUserConfiguration`	Raised when user configuration is wrong.	Please, see the configuration example
`VaultInstanceNotSet`	Raised when the Vault instance is not set.	Please, see documentation
`FailedDeterminateRateLimit`	Raised when the rate limit cannot be determined.	Please, check misconfiguration between configuration and users requests in PostgreSQL
`StorageInstanceNotSet`	Raised when the storage instance (PostgreSQL) is not set.	Please, see documentation
`FailedStorageConnection`	Raised when the connection to the storage (PostgreSQL) failed.	Please, check the connection to the PostgreSQL server

Users class

Class Initialization

The Users class provides authentication, authorization, user attribute management and user request logging for Telegram bots. You can initialize it with different options

vault (any): Configuration for initializing the Vault client.
- (VaultClient): an already initialized instance for interacting with the Vault API.
- (dict): configuration for initializing a VaultClient instance in this class.
rate_limits (bool): Enable rate limit functionality.
storage (dict): Configuration for initializing the storage client.
- db_role (str): The role name for the Vault database engine.

Examples:

Initialize with VaultClient and without rate_limits:

users_without_ratelimits = Users(vault=vault_client, rate_limits=False, storage_connection=psycopg2.connect(**db_config))

Initialize with VaultClient and with rate_limits:

users_with_ratelimits = Users(vault=vault_client, storage_connection=psycopg2.connect(**db_config))

Initialize with Vault configuration dictionary:

vault_config = {
  'namespace': 'my_project',
  'url': 'https://vault.example.com',
  'auth': {
      'type': 'approle',
      'role_id': 'my_role_id',
      'secret_id': 'my_secret_id'
  }
}
users_with_dict_vault = Users(vault=vault_config, storage_connection=psycopg2.connect(**db_config))

method: User Access Check

The user_access_check() method is the main entry point for authentication, authorization, and request rate limit verification. It is used to control the request rate (limits) for a specific user.

Arguments:
- user_id (str): Required user ID.
- role_id (str): Required role ID for the specified user ID.
Keyword Arguments:
- chat_id (str): Required chat ID for the specified user ID. Additional context for logging.
- message_id (str): Required message ID for the specified user ID. Additional context for logging.

Examples:

user_access_check(user_id='user1', role_id='admin_role', chat_id='chat1', message_id='msg1')

Returns:

A dictionary with access status, permissions, and rate limit information.

{
  'access': self.user_status_allow / self.user_status_deny,
  'permissions': self.user_status_allow / self.user_status_deny,
  'rate_limits': '2023-08-06 11:47:09.440933' / None
}

Description of class attributes

Data Type	Attribute	Purpose	Default Value
`object`	`vault`	Vault instance for interacting with the Vault API.	`None`
`dict`	`storage`	Configuration for initializing the storage client.	`None`
`bool`	`rate_limits`	Enable request rate limit functionality.	`True`
`str`	`user_status_allow`	User access status: allowed.	`"allowed"`
`str`	`user_status_deny`	User access status: denied.	`"denied"`
`str`	`vault_config_path`	The prefix of the configuration path in the Vault.	`"configuration/users"`

RateLimiter class

Class Initialization

The RateLimiter class provides restriction functionality for user requests to the Telegram bot in the context of a specific user.

vault (VaultClient): An already initialized instance for interacting with the Vault API or a configuration dictionary for initializing a VaultClient instance in this class.
storage (Storage): An already initialized instance for interacting with the storage (PostgreSQL) or a configuration dictionary for initializing a Storage instance in this class.
user_id (str): User ID for checking speed limits.

Examples:

limiter = RateLimiter(vault=vault_client, storage=storage_client, user_id='User1')

method: Rate Limit Determination

The determine_rate_limit() method is the main entry point for checking bot request limits for the specified user. It returns information about whether the request rate limits are active and when they expire

Examples:
```
determine_rate_limit()
```
Returns:
- String with a timestamp of the end of restrictions on requests or None if rate limit is not applied.
```
("2023-08-07 10:39:00.000000" | None)
```

method: Get User Requests Counters

The get_user_request_counters() method calculates the number of requests made by the user and returns the number of requests per day and per hour.

Examples:
```
get_user_request_counters()
```
Returns:
- A dictionary with the number of requests per day and per hour.
```
{
  'requests_per_day': 9,
  'requests_per_hour': 1
}
```

Description of Class Attributes

Data Type	Attribute	Purpose	Default Value
`VaultClient`	`vault`	Vault instance for interacting with the Vault API.	`None`
`Storage`	`storage`	Storage instance for interacting with the storage (PostgreSQL).	`None`
`str`	`user_id`	User ID for checking speed limits.	`None`
`str`	`vault_config_path`	The prefix of the configuration path in the Vault.	`"configuration/users"`
`dict`	`requests_configuration`	User request limits configuration.	`None`
`dict`	`requests_counters`	Counters for the number of requests per day and per hour.	`None`

Structure of configuration in Vault

This project uses a Vault server with the KV2 engine and Database Engine for storing user configurations and database connection data. It supports user configurations to define system access rights, roles, and request restrictions.

Users Configuration

path to the secret: configuration/users/{user_id}
keys and Values:
- status: The status of user access, which can be either
  - self.user_status_allow
  - self.user_status_deny
- roles: A list of roles associated with the user ID, e.g., ["role1", "role2"].
- requests: Limits on the number of requests
  - requests_per_day
  - requests_per_hour
  - random_shift_time (additional, random shift in minutes from 0 to the specified number) in minutes
example of a secret with configuration:

{
  "status": "allowed",
  "roles": ["admin_role", "additional_role"],
  "requests": {
    "requests_per_day": 10,
    "requests_per_hour": 1,
    "random_shift_minutes": 15
  }
}

Database Configuration

path to the secret: configuration/database
keys and values:
- host: The host of the PostgreSQL server.
- port: The port of the PostgreSQL server.
- database: The name of the PostgreSQL database.
- user: The username for the PostgreSQL database.
- password: The password for the PostgreSQL database.
```
{
  "host": "localhost",
  "port": 5432,
  "database": "mydatabase",
  "user": "myuser",
  "password": "mypassword",
}
```

Structure of historical data in PostgreSQL

This project uses a PostgreSQL database to store historical data about user requests and access events. It supports user request logging to track user activity and access rights. The detailed table schema can be found in this sql file.

Users Requests Table

Contains records of user requests, access permission, access level, and apply limits on the number of requests.

Users Table

Contains records of user metadata for the Telegram bot, such as user ID, chat ID, and message ID.

Additional usage example

Example 1 - With Rate Limits

# import modules
from vault import VaultClient
from users import Users

# create the vault client
vault_client = VaultClient(
  url='http://0.0.0.0:8200',
  namespace='my_project',
  auth={
      'type': 'approle',
      'role_id': 'my_role',
      'secret_id': 'my_secret_id'
  }
)

# create the Users instance of the class with rate limits and get user information
users = Users(vault=vault_client, rate_limits=True, storage_connection=psycopg2.connect(**db_config))
user_info = users.user_access_check(user_id=message.chat.id, role_id="admin_role", chat_id=message.chat.id, message_id=message.message_id)

# check permissions, roles, and rate limits
if user_info["access"] == users.user_status_allow:
    print("Hi, you can use the bot!")
    if user_info["permissions"] == users.user_status_allow:
        if user_info["rate_limits"]:
            print(f"You have sent too many requests, the limit is applied until {user_info['rate_limits']}")
        else:
            print("You have admin's rights")
    else:
        print("You do not have access rights to this function")
else:
    print("Access denied, goodbye!")

Example 2 - Without Rate Limits

# import modules
from vault import VaultClient
from users import Users

# create the vault client
vault_client = VaultClient(
  url='http://vault.example.com',
  namespace='my_project',
  auth={
      'type': 'approle',
      'role_id': 'my_role',
      'secret_id': 'my_secret_id'
  }
)

# create the Users instance of the class without rate limits and get user information
users = Users(vault=vault_client, storage_connection=psycopg2.connect(**db_config))
user_info = users.user_access_check(user_id=message.chat.id, role_id="admin_role", chat_id=message.chat.id, message_id=message.message_id)

# check permissions and roles
if user_info["access"] == users.user_status_allow:
    print("Hi, you can use the bot!")
    if user_info["permissions"] == users.user_status_allow:
        print("You have admin's rights")
    else:
        print("You do not have access rights to this function")
else:
    print("Access denied, goodbye!")

Installing

tee -a pyproject.toml <<EOF
[tool.poetry]
name = myproject"
version = "1.0.0"
description = ""

[tool.poetry.dependencies]
python = "^3.12"
users = { git = "https://github.com/obervinov/users-package.git", tag = "v4.0.0" }

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"
EOF

poetry install

GitHub Actions

Name	Version
GitHub Actions Templates	v2.0.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Users Package

About this project

Description of module Constants

Description of module Exceptions

Users class

Class Initialization

method: User Access Check

Description of class attributes

RateLimiter class

Class Initialization

method: Rate Limit Determination

method: Get User Requests Counters

Description of Class Attributes

Structure of configuration in Vault

Users Configuration

Database Configuration

Structure of historical data in PostgreSQL

Users Requests Table

Users Table

Additional usage example

Installing

GitHub Actions

Files

README.md

Latest commit

History

README.md

File metadata and controls

Users Package

About this project

Description of module Constants

Description of module Exceptions

Users class

Class Initialization

method: User Access Check

Description of class attributes

RateLimiter class

Class Initialization

method: Rate Limit Determination

method: Get User Requests Counters

Description of Class Attributes

Structure of configuration in Vault

Users Configuration

Database Configuration

Structure of historical data in PostgreSQL

Users Requests Table

Users Table

Additional usage example

Installing

GitHub Actions