@chill-sharp/ui-core 1.1.12

package/doc/HowTo/05-docker-env-variables.md

@@ -0,0 +1,274 @@
+# HOW-TO: Create a Docker Image and Configure It with Environment Variables
+
+Versione italiana: [Italiano](../it/HowTo/05-docker-env-variables.md)
+
+This example shows how to package a ChillSharp API into a Docker image and configure it at runtime through environment variables instead of hardcoded values.
+
+## Goal
+
+Build one container image that can be reused across environments by changing only environment variables.
+
+## 1. Read configuration from environment-aware `IConfiguration`
+
+ASP.NET Core already maps environment variables into `builder.Configuration`. Use that instead of hardcoding the SQLite path, module toggles, token lifetimes, SMTP settings, or root-user credentials.
+
+For the DTO date/time mapper, ChillSharp also reads `CHILLSHARP_SYSTEM_TIMEZONE` directly from the process environment. It should be an IANA id such as `Europe/Rome`.
+
+This setting is used for ChillSharp `DateTime` handling and for UTC-to-local normalization of some `DateTimeOffset` inputs. `DateOnly` and `TimeOnly` keep normal .NET string output.
+
+`ChillSharp.Attachment` also reads `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT` directly. In containers, point it at a mounted volume such as `/attachments`.
+
+```csharp
+using ChillSharp.Api;
+using ChillSharp.Auth;
+using ChillSharp.Auth.Api;
+using ChillSharp.Attachment.Services;
+using Microsoft.AspNetCore.Identity;
+using Microsoft.EntityFrameworkCore;
+
+var builder = WebApplication.CreateBuilder(args);
+
+var databasePath = builder.Configuration["CHILLSHARP_DB_PATH"] ?? "/data/blogging.db";
+var attachmentArchiveRoot = builder.Configuration["CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT"] ?? "/attachments";
+
+builder.Services.AddDbContext<BloggingContext>(options =>
+    options.UseSqlite($"Data Source={databasePath}"));
+
+builder.Services.AddIdentityCore<IdentityUser>()
+    .AddEntityFrameworkStores<BloggingContext>()
+    .AddSignInManager()
+    .AddDefaultTokenProviders();
+
+builder.Services.AddAuthentication(ChillAuthIdentityDefaults.AuthenticationScheme)
+    .AddChillAuthBearer();
+
+builder.Services.AddAuthorization();
+
+builder.Services.AddChillApi<BloggingContext>(options =>
+{
+    options.ProtectedApi = GetBool("CHILLSHARP_API_PROTECTED", true);
+    options.ApiBasePath = builder.Configuration["CHILLSHARP_API_BASE_PATH"] ?? "/api";
+    options.EnableSchemaApi = GetBool("CHILLSHARP_ENABLE_SCHEMA", true);
+    options.EnableAuthApi = GetBool("CHILLSHARP_ENABLE_AUTH", true);
+    options.EnableI18nApi = GetBool("CHILLSHARP_ENABLE_I18N", true);
+    options.EnableMcpApi = GetBool("CHILLSHARP_ENABLE_MCP", true);
+    options.EnableAttachmentApi = GetBool("CHILLSHARP_ENABLE_ATTACHMENT", false);
+});
+
+builder.Services.AddChillAuthIdentityApi<BloggingContext, IdentityUser>(options =>
+{
+    // ChillSharp reads these two environment variables as defaults:
+    // CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES and CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS.
+    // Set them here only when you want this host startup code to control the mapping explicitly.
+    options.AccessTokenLifetime = TimeSpan.FromMinutes(GetInt("CHILLSHARP_AUTH_ACCESS_TOKEN_MINUTES", 20));
+    options.RefreshTokenLifetime = TimeSpan.FromDays(GetInt("CHILLSHARP_AUTH_REFRESH_TOKEN_DAYS", 14));
+    options.ReturnPasswordResetTokensInResponse = GetBool("CHILLSHARP_AUTH_RETURN_PASSWORD_RESET_TOKENS", false);
+    options.SendPasswordResetEmails = GetBool("CHILLSHARP_AUTH_SEND_PASSWORD_RESET_EMAILS", true);
+    options.InitializeRootUserOnStartup = GetBool("CHILLSHARP_AUTH_INITIALIZE_ROOT_USER", true);
+    options.CreateChillAuthUserForRoot = GetBool("CHILLSHARP_AUTH_CREATE_ROOT_AUTH_USER", true);
+    options.PasswordResetEmailSubject = builder.Configuration["CHILLSHARP_AUTH_PASSWORD_RESET_SUBJECT"] ?? "Reset your password";
+    options.PasswordResetUrlBase = builder.Configuration["CHILLSHARP_AUTH_PASSWORD_RESET_URL"];
+    options.SmtpHost = builder.Configuration["CHILLSHARP_SMTP_HOST"];
+    options.SmtpPort = GetInt("CHILLSHARP_SMTP_PORT", 587);
+    options.SmtpEnableSsl = GetBool("CHILLSHARP_SMTP_ENABLE_SSL", true);
+    options.SmtpUserName = builder.Configuration["CHILLSHARP_SMTP_USERNAME"];
+    options.SmtpPassword = builder.Configuration["CHILLSHARP_SMTP_PASSWORD"];
+    options.PasswordResetFromEmail = builder.Configuration["CHILLSHARP_SMTP_FROM_EMAIL"];
+    options.PasswordResetFromDisplayName = builder.Configuration["CHILLSHARP_SMTP_FROM_DISPLAY_NAME"];
+});
+
+builder.Services.Configure<ChillAttachmentOptions>(options =>
+{
+    options.ArchiveRoot = attachmentArchiveRoot;
+});
+
+var app = builder.Build();
+
+app.UseAuthentication();
+app.UseAuthorization();
+
+Directory.CreateDirectory(Path.GetDirectoryName(databasePath)!);
+Directory.CreateDirectory(attachmentArchiveRoot);
+
+using (var scope = app.Services.CreateScope())
+{
+    var db = scope.ServiceProvider.GetRequiredService<BloggingContext>();
+    db.Database.EnsureCreated();
+}
+
+app.MapChillApi();
+app.Run();
+
+bool GetBool(string name, bool defaultValue)
+{
+    return bool.TryParse(builder.Configuration[name], out var value) ? value : defaultValue;
+}
+
+int GetInt(string name, int defaultValue)
+{
+    return int.TryParse(builder.Configuration[name], out var value) ? value : defaultValue;
+}
+```
+
+The MCP and attachment modules are registered by `AddChillApi<TContext>()` only when the `DbContext` implements their required interfaces:
+
+- `ChillSharp.Schema` and `ChillSharp.Mcp`: `IChillSchemaDbContext`
+- `ChillSharp.Auth`: `IChillAuthDbContext`
+- `ChillSharp.I18n`: `IChillI18nDbContext`
+- `ChillSharp.Attachment`: `IChillAttachmentDbContext`
+
+Keep `CHILLSHARP_ENABLE_ATTACHMENT=false` until your context exposes the attachment model and archive storage. Then switch it to `true` and keep `/attachments` mounted.
+
+## 2. Use environment variables for modules and runtime settings
+
+These names are a good container baseline for the current built-in modules:
+
+```text
+CHILLSHARP_DB_PATH
+CHILLSHARP_SYSTEM_TIMEZONE
+CHILLSHARP_API_PROTECTED
+CHILLSHARP_API_BASE_PATH
+CHILLSHARP_ENABLE_SCHEMA
+CHILLSHARP_ENABLE_AUTH
+CHILLSHARP_ENABLE_I18N
+CHILLSHARP_ENABLE_MCP
+CHILLSHARP_ENABLE_ATTACHMENT
+CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT
+```
+
+`CHILLSHARP_ENABLE_*` variables are example-host variables: your app reads them from `IConfiguration` and maps them to `ChillApiOptions`. `CHILLSHARP_API_BASE_PATH` defaults to `/api` and is also read by ChillSharp when you do not set `ChillApiOptions.ApiBasePath` explicitly. `CHILLSHARP_SYSTEM_TIMEZONE`, `CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT`, and the root-user variables below are read directly by ChillSharp services too.
+
+When enabled, the default endpoints include:
+
+```text
+http://localhost:8080/api/chill
+http://localhost:8080/api/chill-auth
+http://localhost:8080/api/chill-attachment
+http://localhost:8080/api/chill-mcp
+```
+
+## 3. Use environment variables for the root user
+
+`AddChillAuthIdentityApi(...)` already knows these variables:
+
+```text
+CHILLSHARP_AUTH_ROOT_USERNAME
+CHILLSHARP_AUTH_ROOT_PASSWORD
+CHILLSHARP_AUTH_ROOT_EMAIL
+CHILLSHARP_AUTH_ROOT_DISPLAY_NAME
+```
+
+When `CreateChillAuthUserForRoot = true`, the root `AuthUser` is also created with `CanManagePermissions = true`.
+
+## 4. Create the Dockerfile
+
+This image builds the application once and runs it with the ASP.NET Core runtime image.
+
+```dockerfile
+FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
+WORKDIR /src
+
+COPY MyBlogApp.csproj ./
+RUN dotnet restore
+
+COPY . ./
+RUN dotnet publish -c Release -o /app/out
+
+FROM mcr.microsoft.com/dotnet/aspnet:8.0
+WORKDIR /app
+
+COPY --from=build /app/out ./
+
+ENV ASPNETCORE_URLS=http://+:8080
+ENV CHILLSHARP_DB_PATH=/data/blogging.db
+ENV CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome
+ENV CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/attachments
+
+VOLUME ["/data"]
+VOLUME ["/attachments"]
+EXPOSE 8080
+
+ENTRYPOINT ["dotnet", "MyBlogApp.dll"]
+```
+
+## 5. Build the image
+
+```bash
+docker build -t myblogapp:latest .
+```
+
+## 6. Run the container with environment variables
+
+This example starts the API, persists SQLite data and attachment files in local Docker volumes, and creates the root administrator at startup.
+
+```bash
+docker run --rm -p 8080:8080 \
+  -v myblogapp-data:/data \
+  -v myblogapp-attachments:/attachments \
+  -e CHILLSHARP_DB_PATH=/data/blogging.db \
+  -e CHILLSHARP_SYSTEM_TIMEZONE=Europe/Rome \
+  -e CHILLSHARP_API_PROTECTED=true \
+  -e CHILLSHARP_ENABLE_SCHEMA=true \
+  -e CHILLSHARP_ENABLE_AUTH=true \
+  -e CHILLSHARP_ENABLE_I18N=true \
+  -e CHILLSHARP_ENABLE_MCP=true \
+  -e CHILLSHARP_ENABLE_ATTACHMENT=false \
+  -e CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT=/attachments \
+  -e CHILLSHARP_AUTH_ROOT_USERNAME=root \
+  -e CHILLSHARP_AUTH_ROOT_PASSWORD=Pass123$ \
+  -e CHILLSHARP_AUTH_ROOT_EMAIL=root@example.com \
+  -e CHILLSHARP_AUTH_ROOT_DISPLAY_NAME="Root Administrator" \
+  myblogapp:latest
+```
+
+With the values above, the application is then available at:
+
+```text
+http://localhost:8080/api/chill
+http://localhost:8080/api/chill-auth
+http://localhost:8080/api/chill-mcp
+```
+
+Set `CHILLSHARP_ENABLE_ATTACHMENT=true` when the host context implements `IChillAttachmentDbContext`; then the attachment API is available at `http://localhost:8080/api/chill-attachment`.
+
+## 7. Optional `docker compose` example
+
+```yaml
+services:
+  myblogapp:
+    image: myblogapp:latest
+    build: .
+    ports:
+      - "8080:8080"
+    environment:
+      ASPNETCORE_URLS: http://+:8080
+      CHILLSHARP_DB_PATH: /data/blogging.db
+      CHILLSHARP_SYSTEM_TIMEZONE: Europe/Rome
+      CHILLSHARP_API_PROTECTED: "true"
+      CHILLSHARP_API_BASE_PATH: /api
+      CHILLSHARP_ENABLE_SCHEMA: "true"
+      CHILLSHARP_ENABLE_AUTH: "true"
+      CHILLSHARP_ENABLE_I18N: "true"
+      CHILLSHARP_ENABLE_MCP: "true"
+      CHILLSHARP_ENABLE_ATTACHMENT: "false"
+      CHILLSHARP_ATTACHMENT_ARCHIVE_ROOT: /attachments
+      CHILLSHARP_AUTH_ROOT_USERNAME: root
+      CHILLSHARP_AUTH_ROOT_PASSWORD: Pass123$
+      CHILLSHARP_AUTH_ROOT_EMAIL: root@example.com
+      CHILLSHARP_AUTH_ROOT_DISPLAY_NAME: Root Administrator
+    volumes:
+      - myblogapp-data:/data
+      - myblogapp-attachments:/attachments
+
+volumes:
+  myblogapp-data:
+  myblogapp-attachments:
+```
+
+## Notes
+
+- Keep the image generic and push environment-specific values into runtime configuration.
+- Persist SQLite under a mounted volume, otherwise the database is lost when the container is removed.
+- For production, inject secrets through your container platform or secret manager instead of hardcoding them in `docker run` history or `compose` files.
+
+Next example: [Handle a one-to-many Blog-Posts relation and fetch it in one client call](05-blog-posts-one-to-many.md)

package/doc/HowTo/06-chunk-transactions-autocomplete.md

@@ -0,0 +1,196 @@
+# HOW-TO: Use Chunk, Transactions, and Autocomplete
+
+Versione italiana: [Italiano](../it/HowTo/06-chunk-transactions-autocomplete.md)
+
+This example shows how to send multiple ChillSharp operations in one call with `chunk`, how to wrap write operations in one database transaction, and how to use `autocomplete` for entity and query DTOs.
+
+## Goal
+
+Use the core ChillSharp API efficiently when the client must:
+
+- execute several operations in one HTTP request
+- commit a group of writes atomically
+- ask the server to complete or normalize DTO values before saving
+
+## 1. Prepare the client
+
+All examples below use the .NET client and assume the core API is mapped at `/api/chill`.
+
+```csharp
+using ChillSharp.Client;
+using ChillSharp.Client.Dto;
+
+var client = new ChillSharpClient("http://localhost:5000/api/chill");
+```
+
+## 2. Send multiple operations with `chunk`
+
+`chunk` sends a list of `ChillOperation` items to `/api/chill/chunk`.
+Each operation can contain a `Query` or an `Entity`, depending on the `Verb`.
+
+Set `Index` explicitly when execution order matters.
+
+```csharp
+using ChillSharp.Client.Dto;
+
+var firstPost = new ChillDtoEntity
+{
+    ChillType = "Model.Post",
+    Guid = Guid.Parse("11111111-1111-1111-1111-111111111111")
+};
+firstPost.Properties["Title"] = "First";
+firstPost.Properties["Author"] = "Ada";
+
+var secondPost = new ChillDtoEntity
+{
+    ChillType = "Model.Post",
+    Guid = Guid.Parse("22222222-2222-2222-2222-222222222222")
+};
+secondPost.Properties["Title"] = "Second";
+secondPost.Properties["Author"] = "Linus";
+
+var updateFirstPost = new ChillDtoEntity
+{
+    ChillType = "Model.Post",
+    Guid = firstPost.Guid
+};
+updateFirstPost.Properties["Title"] = "First updated";
+
+var operations = client.Chunk(new List<ChillOperation>
+{
+    new() { Index = 0, Verb = ChillOperationVerb.CREATE, Entity = firstPost },
+    new() { Index = 1, Verb = ChillOperationVerb.CREATE, Entity = secondPost },
+    new() { Index = 2, Verb = ChillOperationVerb.UPDATE, Entity = updateFirstPost }
+});
+```
+
+What this gives you:
+
+- one HTTP request instead of three
+- ordered execution through `Index`
+- one combined response containing the processed operations
+
+## 3. Wrap a chunk in one transaction
+
+Use `transaction` and `commit` when all enclosed write operations must succeed or fail together.
+
+```csharp
+var blog = new ChillDtoEntity
+{
+    ChillType = "Model.Blog",
+    Guid = Guid.NewGuid()
+};
+blog.Properties["Name"] = "Batch blog";
+blog.Properties["Url"] = "https://example.local/batch-blog";
+
+var post = new ChillDtoEntity
+{
+    ChillType = "Model.Post",
+    Guid = Guid.NewGuid()
+};
+post.Properties["Title"] = "Batch post";
+post.Properties["Blog"] = blog.Mock();
+
+var transactionalOperations = client.Chunk(new List<ChillOperation>
+{
+    new() { Index = 0, Verb = ChillOperationVerb.TRANSACTION },
+    new() { Index = 1, Verb = ChillOperationVerb.CREATE, Entity = blog },
+    new() { Index = 2, Verb = ChillOperationVerb.CREATE, Entity = post },
+    new() { Index = 3, Verb = ChillOperationVerb.COMMIT }
+});
+```
+
+Use this pattern only for the write operations that must share the same database transaction.
+If one operation fails before `commit`, the transaction is not committed.
+
+## 4. Autocomplete an entity DTO
+
+`autocomplete` uses the same DTO style as `create`, `update`, and `delete`, but it calls `/api/chill/autocomplete`.
+
+For entities, ChillSharp performs `OnAutocomplete(...)` without persisting changes:
+
+- if the entity already exists, it is loaded from the current `DbContext`
+- otherwise it is attached in `Added` state
+- the autocomplete logic runs inside a temporary transaction
+- the transaction is rolled back at the end, so the database is unchanged
+
+This is useful for previewing computed values such as slugs, labels, derived text, or default field combinations.
+
+```csharp
+var draftBlog = new ChillDtoEntity
+{
+    ChillType = "Model.Blog",
+    Guid = Guid.NewGuid()
+};
+draftBlog.Properties["Title"] = "  My first ChillSharp blog  ";
+
+var autocompletedBlog = client.Autocomplete(draftBlog);
+
+Console.WriteLine(autocompletedBlog.GetString("Title"));
+Console.WriteLine(autocompletedBlog.GetString("Url"));
+```
+
+Typical entity-side logic:
+
+```csharp
+public override void OnAutocomplete(IChillContext context)
+{
+    base.OnAutocomplete(context);
+
+    Title = Title?.Trim();
+
+    if (string.IsNullOrWhiteSpace(Url) && !string.IsNullOrWhiteSpace(Title))
+    {
+        Url = "/blogs/" + Title.ToLowerInvariant().Replace(' ', '-');
+    }
+}
+```
+
+## 5. Autocomplete a query DTO
+
+Queries also use `/api/chill/autocomplete`, but they do not participate in the EF Core context transaction flow.
+The query DTO is simply passed through `OnAutocomplete(...)` on the resolved `IChillQuery`.
+
+This is useful for normalizing filters before `Query(...)`, for example:
+
+- trimming text inputs
+- expanding a search box into a full-text field
+- setting default paging or sorting values
+
+```csharp
+var blogQuery = new ChillDtoQuery
+{
+    ChillType = "Query.BlogQuery"
+};
+blogQuery.Properties["Title"] = "  chillsharp  ";
+
+var autocompletedQuery = client.Autocomplete(blogQuery);
+
+Console.WriteLine(autocompletedQuery.GetString("Title"));
+Console.WriteLine(autocompletedQuery.GetString("FullTextSearch"));
+```
+
+Typical query-side logic:
+
+```csharp
+public override void OnAutocomplete(IChillContext context)
+{
+    base.OnAutocomplete(context);
+
+    Title = Title?.Trim();
+
+    if (!string.IsNullOrWhiteSpace(Title))
+    {
+        FullTextSearch = Title;
+    }
+}
+```
+
+## 6. Choose the right API
+
+- use `create`, `update`, and `delete` when the operation must change the database immediately
+- use `chunk` when several operations should travel in one request
+- use `transaction` plus `commit` inside `chunk` when multiple writes must be atomic
+- use `autocomplete` when the server should calculate or normalize values without saving them
+
+Next: [Back to the documentation index](../README.md)