feat: Realm helper with required and optional parameters separated (#164)

* added realm helper with required and optional parameters separated

* bump Rust requirement to 1.88

* lower Rust requirement to 1.87

* added integration example and corrected field visibility

* added comments

* updated release automation script, split into smaller modules

* fixed resource modules visibility

* added builder implementation

* cleanup empty modules

* align core and resource add user examples

* removed not needed permission from release automation

* split generation into submethods

* full comments on root methods

* remove builder and resource from default features, add group feature to activate both

* update docs

* do not run doctests with default features

Author: kilork

.github/workflows/integration.yml

@@ -15,21 +15,23 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: dtolnay/rust-toolchain@1.84.0
+    - uses: dtolnay/rust-toolchain@1.87.0
     - run: mkdir .cargo && cp .cargo-config.toml .cargo/config.toml
-    - name: Build
+    - name: Build with default features
       run: cargo build
-    - name: Run unit tests
-      run: cargo test
-    - name: Build with features
-      run: cargo build --features=rc,schemars
-    - name: Run unit tests with features
-      run: cargo test --features=rc,schemars
+    - name: Run unit tests with default features
+      run: cargo test --lib
+    - name: Build with all top level features
+      run: cargo build --features=rc,schemars,multipart,resource-builder
+    - name: Run unit tests with all top level features
+      run: cargo test --features=rc,schemars,multipart,resource-builder
     - name: Run integration tests
       run: |
         export KEYCLOAK_VERSION=`cargo metadata --no-deps --format-version 1 | jq '.packages[0].version | split(".") | map(tonumber) | .[:-1] + [.[2] / 100] | map(floor) | join(".")' | tr -d '"'`
         docker run -p 8080:8080 --name keycloak -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=password -e KC_FEATURES=admin-api quay.io/keycloak/keycloak:${KEYCLOAK_VERSION} start-dev &
         sleep 40
         cargo run --example=adduser
+        cargo run --example=resource_adduser --features=resource-builder
         cargo run --example=importconfig --features=multipart
-        cargo run --example=adduser --features=rc,schemars,multipart
+        cargo run --example=adduser --features=rc,schemars,multipart,resource-builder
+        cargo run --example=resource_adduser --features=rc,schemars,multipart,resource-builder

Cargo.toml

@@ -11,39 +11,19 @@ homepage = "https://github.com/kilork/keycloak"
 keywords = ["api", "async", "keycloak", "rest"]
 license = "Unlicense OR MIT"
 repository = "https://github.com/kilork/keycloak"
-rust-version = "1.84"
+rust-version = "1.87"
 
 [features]
 default = ["tags-all"]
+resource-builder = ["builder", "resource"]
 schemars = ["dep:schemars"]
 multipart = ["reqwest/multipart"]
 rc = ["rc-map", "rc-str", "rc-val", "rc-vec"]
 rc-map = ["serde/rc"]
 rc-str = ["serde/rc"]
 rc-val = ["serde/rc"]
 rc-vec = ["serde/rc"]
-tags-all = [
-    "tag-attack-detection",
-    "tag-authentication-management",
-    "tag-client-attribute-certificate",
-    "tag-client-initial-access",
-    "tag-client-registration-policy",
-    "tag-client-role-mappings",
-    "tag-client-scopes",
-    "tag-clients",
-    "tag-component",
-    "tag-groups",
-    "tag-identity-providers",
-    "tag-key",
-    "tag-organizations",
-    "tag-protocol-mappers",
-    "tag-realms-admin",
-    "tag-role-mapper",
-    "tag-roles",
-    "tag-roles-by-id",
-    "tag-scope-mappings",
-    "tag-users",
-]
+tags-all = ["tag-attack-detection", "tag-authentication-management", "tag-client-attribute-certificate", "tag-client-initial-access", "tag-client-registration-policy", "tag-client-role-mappings", "tag-client-scopes", "tag-clients", "tag-component", "tag-groups", "tag-identity-providers", "tag-key", "tag-organizations", "tag-protocol-mappers", "tag-realms-admin", "tag-role-mapper", "tag-roles", "tag-roles-by-id", "tag-scope-mappings", "tag-users", "tag-none"]
 tag-attack-detection = []
 tag-authentication-management = []
 tag-client-attribute-certificate = []
@@ -64,6 +44,9 @@ tag-roles = []
 tag-roles-by-id = []
 tag-scope-mappings = []
 tag-users = []
+tag-none = []
+resource = []
+builder = []
 
 [dependencies]
 reqwest = { version = "0.12", default-features = false, features = ["json"] }
@@ -79,7 +62,7 @@ percent-encoding = "2.3.1"
 [dev-dependencies]
 tokio = { version = "1", features = ["full"] }
 heck = "0.5"
-clap = { version = "4", features = ["derive", "std"], default-features = false }
+clap = { version = "4", features = ["derive", "help", "std"], default-features = false }
 toml = "0.8"
 serde = { version = "1", features = ["derive", "rc"] }
 indexmap = { version = "2", features = ["serde"] }

README.md

@@ -16,10 +16,11 @@ Default flags: `tags-all`.
 - `schemars`: add [schemars](https://crates.io/crates/schemars) support.
 - `multipart`: add multipart support to reqwest, enabling extra methods in API.
 - `tags-all`: activate all tags (resource groups) in REST API, it is default behavior. Disable default features and use individual `tag-xxx` features to activate only required resource groups. For a full list reference the [Cargo.toml](Cargo.toml).
+- `resource-builder`: add resource builder support.
 
 ## Usage
 
-Requires Rust version >= `1.84.0`.
+Requires Rust version >= `1.87.0`.
 
 Add dependency to Cargo.toml:
 
@@ -29,51 +30,44 @@ keycloak = "~26.3"
 ```
 
 ```rust
-use keycloak::{
-    types::*,
-    {KeycloakAdmin, KeycloakAdminToken},
-};
-
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    use keycloak::{types::*, KeycloakAdmin, KeycloakAdminToken};
+
+    const REALM: &str = "resource";
+
     let url = std::env::var("KEYCLOAK_ADDR").unwrap_or_else(|_| "http://localhost:8080".into());
     let user = std::env::var("KEYCLOAK_USER").unwrap_or_else(|_| "admin".into());
     let password = std::env::var("KEYCLOAK_PASSWORD").unwrap_or_else(|_| "password".into());
 
     let client = reqwest::Client::new();
     let admin_token = KeycloakAdminToken::acquire(&url, &user, &password, &client).await?;
 
-    eprintln!("{:?}", admin_token);
+    eprintln!("{admin_token:?}");
 
     let admin = KeycloakAdmin::new(&url, admin_token, client);
 
     admin
         .post(RealmRepresentation {
-            realm: Some("test".into()),
+            realm: Some(REALM.into()),
             ..Default::default()
         })
         .await?;
 
-    let response = admin
-        .realm_users_post(
-            "test",
-            UserRepresentation {
-                username: Some("user".into()),
-                ..Default::default()
-            },
-        )
+    let realm = admin.realm(REALM);
+
+    let response = realm
+        .users_post(UserRepresentation {
+            username: Some("user".into()),
+            ..Default::default()
+        })
         .await?;
 
     eprintln!("{:?}", response.to_id());
 
-    let users = admin
-        .realm_users_get(
-            "test", None, None, None, None, None, None, None, None, None, None, None, None, None,
-            None,
-        )
-        .await?;
+    let users = realm.users_get().username("user".to_string()).await?;
 
-    eprintln!("{:?}", users);
+    eprintln!("{users:?}");
 
     let id = users
         .iter()
@@ -84,12 +78,9 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .unwrap()
         .to_string();
 
-    admin
-        .realm_users_with_user_id_delete("test", id.as_str())
-        .await?;
-
-    admin.realm_delete("test").await?;
+    realm.users_with_user_id_delete(id.as_str()).await?;
 
+    realm.delete().await?;
     Ok(())
 }
 ```
@@ -106,5 +97,5 @@ Example: official version `13.0.1` is `13.0.100` for crate version. `13.0.102` m
 To update current version use provided [update.ts](./update.ts) `deno` script:
 
 ```sh
-deno run --allow-env=KEYCLOAK_RUST_VERSION,KEYCLOAK_VERSION,KEYCLOAK_RUST_MAJOR_VERSION --allow-read=Cargo.toml --allow-write=Cargo.toml,api/openapi.json,src/types.rs,src/rest/generated_rest.rs --allow-net=keycloak.org,www.keycloak.org --allow-run=cargo,gh,git,handlebars-magic update.ts
+deno run --allow-env=KEYCLOAK_RUST_VERSION,KEYCLOAK_VERSION,KEYCLOAK_RUST_MAJOR_VERSION --allow-read=Cargo.toml --allow-write=Cargo.toml,api/openapi.json,src/types.rs,src/rest/generated_rest.rs,src/resource --allow-net=keycloak.org,www.keycloak.org --allow-run=cargo,gh,git,handlebars-magic update.ts
 ```

examples/adduser.rs

@@ -1,31 +1,33 @@
-use keycloak::{
-    types::*,
-    {KeycloakAdmin, KeycloakAdminToken},
-};
-
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    use keycloak::{
+        types::*,
+        {KeycloakAdmin, KeycloakAdminToken},
+    };
+
+    const REALM: &str = "test";
+
     let url = std::env::var("KEYCLOAK_ADDR").unwrap_or_else(|_| "http://localhost:8080".into());
     let user = std::env::var("KEYCLOAK_USER").unwrap_or_else(|_| "admin".into());
     let password = std::env::var("KEYCLOAK_PASSWORD").unwrap_or_else(|_| "password".into());
 
     let client = reqwest::Client::new();
     let admin_token = KeycloakAdminToken::acquire(&url, &user, &password, &client).await?;
 
-    eprintln!("{:?}", admin_token);
+    eprintln!("{admin_token:?}");
 
     let admin = KeycloakAdmin::new(&url, admin_token, client);
 
     admin
         .post(RealmRepresentation {
-            realm: Some("test".into()),
+            realm: Some(REALM.into()),
             ..Default::default()
         })
         .await?;
 
     let response = admin
         .realm_users_post(
-            "test",
+            REALM,
             UserRepresentation {
                 username: Some("user".into()),
                 ..Default::default()
@@ -37,12 +39,25 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     let users = admin
         .realm_users_get(
-            "test", None, None, None, None, None, None, None, None, None, None, None, None, None,
+            REALM,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
+            None,
             None,
+            Some("user".into()),
         )
         .await?;
 
-    eprintln!("{:?}", users);
+    eprintln!("{users:?}");
 
     let id = users
         .iter()
@@ -54,10 +69,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
         .to_string();
 
     admin
-        .realm_users_with_user_id_delete("test", id.as_str())
+        .realm_users_with_user_id_delete(REALM, id.as_str())
         .await?;
 
-    admin.realm_delete("test").await?;
+    admin.realm_delete(REALM).await?;
 
     Ok(())
 }