[WIP] crud: introduce basic tarantool 3 roles

This patch introduce basic crud-router and crud-storage roles for Tarantool 3. The roles are similar to Cartridge ones. Roles support Tarantool 3.0.2, Tarantool 3.1.0 and newer due to [1, 2]. This commit does not yet introduce metrics configuration through roles config. [1] tarantool/tarantool#9643 [2] tarantool/tarantool#9649 Part of #415
tarantool · Mar 27, 2024 · 1b0624e · 1b0624e
1 parent 973dc9e
commit 1b0624e
Show file tree

Hide file tree

Showing 12 changed files with 427 additions and 82 deletions.
diff --git a/.github/workflows/test_on_push.yaml b/.github/workflows/test_on_push.yaml
@@ -43,6 +43,8 @@ jobs:
             external-keydef-version: "0.0.4"
           - tarantool-version: "3.0.0"
             vshard-version: "0.1.25"
+          - tarantool-version: "master"
+            vshard-version: "0.1.26"
       fail-fast: false
     # Can't install older versions on 22.04,
     # see https://github.com/tarantool/setup-tarantool/issues/36

diff --git a/README.md b/README.md
@@ -44,8 +44,10 @@ It also provides the `crud-storage` and `crud-router` roles for
       - [Read view select conditions](#read-view-select-conditions)
     - [Read view pairs](#read-view-pairs)
   - [Schema](#schema)
-- [Cartridge roles](#cartridge-roles)
+- [Tarantool 3 roles](#tarantool-3-roles)
   - [Usage](#usage)
+- [Cartridge roles](#cartridge-roles)
+  - [Usage](#usage-1)
 - [License](#license)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -54,38 +56,84 @@ It also provides the `crud-storage` and `crud-router` roles for
 
 First, [install Tarantool](https://www.tarantool.io/en/download).
 
-Now you have the following options for learning the crud API and using it in a
-project:
-
-* Play with crud on a test dataset on a single instance:
-
-  ```shell
-  $ git clone https://github.com/tarantool/crud.git
-  $ cd crud
-  $ tt rocks make
-  $ ./doc/playground.lua
-  tarantool> crud.select('customers', {{'<=', 'age', 35}}, {first = 10})
-  tarantool> crud.select('developers', nil, {first = 6})
-  ```
-* Install crud into the current directory:
-
-  ```shell
-  $ tt rocks install crud
-  ```
-* Add the [crud initialization code](#API) to router and storage instances
-  initialization code for [VShard](https://github.com/tarantool/vshard).
-* Add crud into dependencies of a Cartridge application and add crud roles into
-  dependencies of your roles (see [Cartridge roles](#cartridge-roles) section).
-* Add crud into dependencies of your application (rockspec, RPM spec -- depends
-  on your choice) and call crud initialization code from storage and router
-  code (see [API](#api) section).
+### Install
+
+#### Manual install
+
+To try `crud` in your application, you may install it manually fron web
+with `tt rocks` rock management tool.
+
+```bash
+tt rocks install crud
+```
+
+#### Application dependency
+
+To use crud in your application, set it as a rockspec dependency.
+
+```lua
+package = 'myapp'
+
+version = 'scm-1'
+
+source  = {
+    url = '/dev/null',
+}
+
+dependencies = {
+    'tarantool >= 3.1.0',
+    'crud >= <the-latest-tag>-1',
+}
+
+build = {
+    type = 'none';
+}
+```
+
+#### Repository clone
+
+You can also clone the repository to explore crud and try it inside a sandbox.
+
+```bash
+git clone https://github.com/tarantool/crud.git
+cd crud
+tt rocks make
+```
+
+### Usage
+
+For Tarantool 3.x, enable crud roles on your application instances in a configuration
+(see [Tarantool 3 roles](#tarantool-3-roles) section).
+Roles support Tarantool 3.0.2, Tarantool 3.1.0 and newer.
+Older versions are not supported due to
+[tarantool/tarantool#9643](https://github.com/tarantool/tarantool/issues/9643) and
+[tarantool/tarantool#9649](https://github.com/tarantool/tarantool/issues/9649)
+issues.
+
+For Tarantool 1.10 and 2.x, add crud roles into dependencies of your roles
+(see [Cartridge roles](#cartridge-roles) section).
+
+For Tarantool 1.10, 2.x and 3.x you can also manually call
+the [crud initialization code](#API) on [VShard](https://github.com/tarantool/vshard)
+router and storage instances.
+
+### Sandbox
+
+The repository provide a simple sandbox application with a test dataset on a single instance.
+
+```bash
+./doc/playground.lua
+tarantool> crud.select('customers', {{'<=', 'age', 35}}, {first = 10})
+tarantool> crud.select('developers', nil, {first = 6})
+```
 
 ## API
 
 The CRUD operations should be called from router.
 
 All VShard storages should call `crud.init_storage()` after
-`vshard.storage.cfg()` (or enable the `crud-storage` role for Cartridge)
+`vshard.storage.cfg()` (or enable the `roles.crud-storage` role for Tarantool 3
+or the `crud-storage` role for Cartridge)
 first to initialize storage-side functions that are used to manipulate data
 across the cluster. The storage-side functions have the same access
 as a user calling `crud.init_storage()`. Therefore, if `crud` do not have
@@ -98,7 +146,8 @@ asynchronous bootstrap is used for Tarantool 3.x and
 synchronous bootstrap is used for Tarantool 1.10 and 2.x.
 
 All VShard routers should call `crud.init_router()` after `vshard.router.cfg()`
-(or enable the `crud-router` role for Cartridge) to make `crud` functions
+(or enable the `roles.crud-storage` role for Tarantool 3
+or the `crud-router` role for Cartridge) to make `crud` functions
 callable via `net.box`. If a user is allowed to execute `crud` functions on
 the router-side then the user does not need additional access on storages.
 
@@ -1833,6 +1882,194 @@ crud.schema()
     indexes: ...
 ```
 
+## Tarantool 3 roles
+
+`roles.crud-storage` is a Tarantool 3 role that initializes functions that
+are used on the storage side to perform CRUD operations. Role must be enabled
+on sharding storages.
+
+`cartridge.roles.crud-router` is a role that exposes public `crud` functions
+to the global scope so that you can call them via `net.box` or with connectors.
+Role must be enabled on sharding routers.
+
+Roles support Tarantool 3.0.2, Tarantool 3.1.0 and newer.
+Older versions are not supported due to
+[tarantool/tarantool#9643](https://github.com/tarantool/tarantool/issues/9643) and
+[tarantool/tarantool#9649](https://github.com/tarantool/tarantool/issues/9649)
+issues.
+
+### Usage
+
+1.  Add `crud` to dependencies in the project rockspec.
+
+    **Note**: it's better to use tagged version than `scm-1`.
+    Check the latest available [release](https://github.com/tarantool/crud/releases) tag and use it.
+
+    ```lua
+    -- <project-name>-scm-1.rockspec
+    dependencies = {
+       ...
+       'crud == <the-latest-tag>-1',
+        ...
+    }
+    ```
+
+2.  Add crud roles to your application configuration.
+    Application must be a sharded one.
+    It is required that `roles.crud-storage` is enabled on each
+    sharding storage.
+
+    ```yaml
+        groups:
+          routers:
+            sharding:
+              roles:
+                - router
+            roles:
+              - roles.crud-router
+            replicasets:
+              router:
+
+          storages:
+            sharding:
+              roles:
+                - storage
+            roles:
+              - roles.crud-storage
+            replicasets:
+              s-1:
+              s-2:
+    ```
+
+    <details>
+      <summary>Full configuration example</summary>
+
+      ```yaml
+        credentials:
+          users:
+            replicator:
+              password: replicating
+              roles:
+                - replication
+            storage:
+              password: storing-buckets
+              roles:
+                - sharding
+            guest:
+              roles:
+                - super
+
+        sharding:
+          bucket_count: 30000
+
+        replication:
+          failover: manual
+
+        iproto:
+          advertise:
+            peer:
+              login: replicator
+            sharding:
+              login: storage
+
+        groups:
+          routers:
+            sharding:
+              roles:
+              - router
+            roles:
+              - roles.crud-router
+            replicasets:
+              router:
+                leader: router
+                instances:
+                  router:
+                    iproto:
+                      listen:
+                        - uri: localhost:3301
+          storages:
+            sharding:
+              roles:
+              - storage
+            roles:
+              - roles.crud-storage
+            app:
+              module: mystorage
+            replicasets:
+              s-1:
+                leader: s1-master
+                instances:
+                  s1-master:
+                    iproto:
+                      listen:
+                        - uri: localhost:3302
+                  s1-replica:
+                    iproto:
+                      listen:
+                        - uri: localhost:3303
+              s-2:
+                leader: s2-master
+                instances:
+                  s2-replica:
+                    iproto:
+                      listen:
+                        - uri: localhost:3304
+                  s2-master:
+                    iproto:
+                      listen:
+                        - uri: localhost:3305
+      ```
+    </details>
+
+3. Set up your schema on storages (for example, through `app.module` section in Tarantool 3 configuration.)
+
+    ```lua
+    -- mystorage.lua
+
+    -- Schema setup is idempotent.
+
+
+    box.watch('box.status', function()
+        if box.info.ro then
+            return
+        end
+
+        local customers_space = box.schema.space.create('customers', {
+            format = {
+                {name = 'id', type = 'unsigned'},
+                {name = 'bucket_id', type = 'unsigned'},
+                {name = 'name', type = 'string'},
+                {name = 'age', type = 'number'},
+            },
+            if_not_exists = true,
+        })
+
+        customers_space:create_index('id', {
+            parts = { {field ='id', is_nullable = false} },
+            if_not_exists = true,
+        })
+
+        customers_space:create_index('bucket_id', {
+            parts = { {field ='bucket_id', is_nullable = false} },
+            if_not_exists = true,
+        })
+
+        customers_space:create_index('age', {
+            parts = { {field ='age'} },
+            unique = false,
+            if_not_exists = true,
+        })
+    end)
+    ```
+
+4.  Start the application cluster. You can check whether asynchronous bootstrap
+    had finished through `crud.storage_info()` calls on router.
+
+Now your cluster contains storages that are configured to be used for
+CRUD-operations.
+You can simply call CRUD functions on the router to insert, select, and update
+data across the cluster.
+
 ## Cartridge roles
 
 `cartridge.roles.crud-storage` is a Tarantool Cartridge role that depends on the

diff --git a/crud/common/roles.lua b/crud/common/roles.lua
@@ -0,0 +1,20 @@
+local config = require('config')
+
+local function is_sharding_role_enabled(expected_sharding_role)
+    -- Works only for versions newer than 3.0.1-10 (3.0.2 and following)
+    -- and newer than 3.1.0-entrypoint-77 (3.1.0 and following).
+    -- https://github.com/tarantool/tarantool/commit/ebb170cb8cf2b9c4634bcf0178665909f578c335
+    local actual_sharding_roles = config:get('sharding.roles')
+
+    for _, actual_sharding_role in ipairs(actual_sharding_roles or {}) do
+        if actual_sharding_role == expected_sharding_role then
+            return true
+        end
+    end
+
+    return false
+end
+
+return {
+    is_sharding_role_enabled = is_sharding_role_enabled,
+}