ioToggle.CoreLib 10.0.0

ioToggle.CoreLib

Shared library for ioToggle API projects. Provides base controllers, authentication/permission plumbing, Swagger filters, persistence interfaces, and core data models — so each API project only needs to implement its own domain logic.

What's included

• Base controllers — MainDbController (opens/closes IMainDb per request) and OrganizationController (resolves and validates organization_id from route + claims)
• Ready-made endpoints — accountController (/account/login, /account/current_user, /account/logout) and organizationsController (/organizations)
• Permission enforcement — [Permissions("id")] attribute + PermissionsFilter returning HTTP 403 on failure
• Swagger filters — automatic 401/429/500 responses, organization_uri header injection, permission descriptions
• Middleware — RequestResponseLoggerMiddleware for full request/response logging on 4xx/5xx
• DB connections — IMainDb/IDataDb PostgreSQL connection abstractions (registered as Transient)
• Data adapters — SQL implementations for organizations, members, profiles, permissions, tenants
• Helpers — ByteArrayConverter (hex instead of Base64), HexStringExtension, ClaimsPrincipal.HasPermission()

Quick start

// 1. Register DB connections
builder.Services.AddTransient<IMainDb, SqlMainDb>(provider =>
    new SqlMainDb(new SqlConnectionFactory(builder.Configuration, "maindb").CreateDbConnection()));

// 2. Register Swagger filters
builder.Services.AddSwaggerGen(c =>
{
    c.OperationFilter<Error401OperationFilter>();
    c.OperationFilter<Error429OperationFilter>();
    c.OperationFilter<Error500OperationFilter>();
    c.OperationFilter<OrganizationURIOperationFilter>();
    c.OperationFilter<PermissionsOperationFilter>();
});

// 3. Extend base controllers
[ApiController]
[Route("/{organization_uri:length(0,255)}/devices")]
[Permissions("telemetry/devices/read")]
public class devicesController : OrganizationController
{
    private IDeviceDataAdapter _adapter = default!;

    protected override async Task OnMainDbOpened()
        => _adapter = MainDb.GetDataAdapter<IDeviceDataAdapter>();

    [HttpGet]
    public async Task<IActionResult> Get() => Json(await _adapter.GetAllAsync());
}

Using with AI agents

The file docs/Implementing-API.md provides a comprehensive reference of the library's API, patterns, and usage examples specifically written to help AI coding assistants (such as GitHub Copilot, Claude, or similar tools) generate correct code when working with this library. If you are using an AI agent in your project, point it to that file.

Authors

• Fabien Philippe - Initial work - In