Kawa.Core 0.2.0

Design Principles

Kawa is a contract-first .NET web framework that lays a thin waterway on top of ASP.NET Core.

Kawa keeps application flow centered on request/response contracts and use cases. ASP.NET Core stays as the host and transport layer; Kawa only provides the small boundary pieces needed to execute use cases and translate KawaResult<T> values into HTTP responses.

Packages

• Kawa.Abstractions: shared use case, result, and error contracts
• Kawa.Core: transport-independent use case execution
• Kawa.Web: ASP.NET Core Minimal API integration
• Kawa.FSharp: F# helpers

Installation

dotnet add package Kawa.Web

Kawa.Web brings in the core Kawa runtime pieces needed for ASP.NET Core Minimal API integration.

Quick Start

Define one use case under UseCases/, with its request and response contracts nested in the same source file:

// UseCases/CreateUser.cs
using Kawa.Abstractions;

[KawaUseCase(
    "users.create",
    Summary = "Create user",
    Description = "Creates a user account.",
    Version = "v1",
    Tags = new[] { "Users" })]
[KawaErrorResponse(KawaErrorKind.Validation, Description = "Name is required.")]
public sealed class CreateUser
    : IUseCase<CreateUser.Request, CreateUser.Response>
{
    public sealed record Request(string Name);

    public sealed record Response(string Message);

    public Task<KawaResult<Response>> ExecuteAsync(
        Request request,
        CancellationToken cancellationToken = default)
    {
        if (string.IsNullOrWhiteSpace(request.Name))
        {
            var error = new KawaError(KawaErrorKind.Validation, "Name is required.");
            return Task.FromResult(KawaResult<Response>.Failure(error));
        }

        var response = new Response($"Created user {request.Name}.");
        return Task.FromResult(KawaResult<Response>.Success(response));
    }
}

Register Kawa, scan for use cases, and map the endpoint from the use case type:

using Kawa.Web;

var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddKawa()
    .AddKawaUseCasesFromAssemblies(typeof(CreateUser).Assembly);

var app = builder.Build();

app.MapKawaPost<CreateUser>("/users");

app.Run();

Kawa.Web is intended to expose the same contracts through OpenAPI. The convention is that Kawa request/response contracts are the source of the OpenAPI schema, with Swagger UI and ReDoc available by default in development once the Web OpenAPI setup is enabled.

Use case metadata and error response attributes are transport-independent. Kawa.Web maps them to OpenAPI, and future RPC / CLI / Worker adapters can use the same API catalog.

Then call the endpoint:

curl -X POST http://localhost:5000/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Louisa"}'

Result to HTTP Mapping

MapKawaPost<TUseCase> reads the matching IUseCase<TRequest,TResponse> contract from the use case type, resolves that contract from dependency injection, executes it through UseCaseExecutor, and converts the result to an ASP.NET Core IResult.

MapKawaPost<TRequest,TResponse> is also available when you want to map explicit request and response types.

Current failure mappings:

Samples

Run the C# sample:

dotnet run --project samples/Kawa.Sample.CSharp

Run the mixed C# host + F# use case sample:

dotnet run --project samples/Kawa.Sample.Mixed

Run the mixed C# host + VB.NET use case sample:

dotnet run --project samples/Kawa.Sample.VB

All samples expose POST /users.

Development

Restore, build, and test:

dotnet restore Kawa.sln
dotnet build Kawa.sln --no-restore
dotnet test Kawa.sln --no-restore --no-build

Run tests with coverage:

dotnet test Kawa.sln \
  --no-restore \
  --no-build \
  --collect:"XPlat Code Coverage" \
  --results-directory TestResults \
  -- \
  DataCollectionRunSettings.DataCollectors.DataCollector.Configuration.Format=cobertura

The CI pipeline audits NuGet packages during restore and uploads coverage to Codecov using the repository secret CODECOV_TOKEN. Project and patch coverage are configured to target 100%.

To create local NuGet packages:

bash eng/pack.sh

To publish the generated packages to NuGet.org:

NUGET_API_KEY=... bash eng/push-nuget.sh

NuGet packages and GitHub Releases are published by GitHub Actions when a tag in vX.Y.Z format is pushed, for example:

git tag v0.1.1
git push origin v0.1.1

The release workflow uses the repository secret NUGET_API_KEY.

See:

• Design Principles
• Rails-like Convention Proposal
• 設計思想メモ 日本語版
• Rails-like Convention Proposal 日本語版

License

Kawa is licensed under the MIT License.