Philosophy

The Blazeauth C++ library is designed as a tool, not a framework.

It gives your program a reliable auth/licensing/session transport layer and stays out of the rest of your product. That matters whether you are building a console utility, a desktop UI application, a background service, or software that runs on a networked embedded device.

Core position

What the library owns, and what it leaves to you

This boundary is intentional.

An authorization library should authorize. It should not decide that your user must see a modal dialog, or that your logs belong in std::cerr, or that a recoverable network error deserves a process exit. That kind of runtime interference is outside the library's job.

Runtime contract

Normal failures are returned, not dramatized

The library exposes several ways to handle failure depending on your program's style:

• throwing synchronous calls
• no-throw synchronous calls with std::error_code
• asynchronous callback-based calls
• coroutine-friendly calls

That means the host application chooses its own failure policy. If you want exceptions, you can use them. If you want strict manual control via std::error_code, you can use that. If you want async or coroutine flow, the library supports both.

No UI ownership

The library does not show message boxes, open windows, or talk to any desktop UI framework. There is no Qt/Win32/Cocoa ownership hidden inside it.

No console noise in normal release runtime

In normal release configuration, the library does not print operational errors to the console on its own. API failures and transport/runtime failures are returned to the host program instead.

Honest caveats

• Debug logging exists in debug-oriented builds. BLAZEAUTH_DEBUG_LOGS defaults to enabled under _DEBUG, and those logs go to stdout.
• There is one deliberate fatal misuse guard: destroying blaze::session from its own I/O thread is treated as a programmer error and leads to std::terminate(). That is documented separately in Common pitfalls.

These are deliberate contracts, not “mystery behavior”, and they are outside ordinary runtime error handling.

Resource and behavior discipline

The implementation tries to be boring in the good sense:

• one dedicated internal I/O runtime thread per session
• explicit shutdown and reusable session lifecycle
• no GUI baggage
• no “helpful” background UX decisions
• no forced logging pipeline

The goal is simple: do the network/auth job with as little collateral impact on the host program as possible.

For example:

• shutdown() closes the current connection lifecycle without destroying the session object, so the same session can be reused later.
• session resumption is explicit policy, not magic hidden reconnection theater
• panel events are opt-in
• timeouts can be tuned with with_timeout(...) for synchronous flows

Modern implementation choices

The project is intentionally built on performance-oriented, modern components:

The public library project itself is compiled with modern C++ internally (C++23 in the build), while the external API surface is deliberately designed to be usable from C++14 through current standards.

That split is part of the design philosophy:

• modern internals where they improve implementation quality
• conservative public compatibility where it helps real adopters

Transport and TLS posture

The codebase makes a few priorities clear:

• TLS system context is used for certificate verification
• deprecated TLS versions are disabled
• system CA roots are loaded
• on Windows, the TLS layer supports AIA-fetching certificate verification callback integration

That is the kind of choice we want in this library: practical, deployment-aware security behavior without forcing UI or app-policy decisions onto the host program.

Portability and deployment profile

Official build instructions are documented for:

• Windows
• Linux
• macOS

The platform layer also explicitly recognizes Windows, Linux, Apple, Unix, and POSIX environments.

Because the library is headless and network-focused, it is comfortable inside:

• console tools
• desktop GUI applications
• background services/daemons
• launcher software
• appliance-style software and OS-based embedded products

Embedded, with an honest boundary

It is fair to describe the library as embedded-friendly in the sense that it does not assume any GUI or desktop runtime and it uses portable networking/TLS components.

It would not be honest to market it as bare-metal-first. The project expects a real C++ toolchain, threads, sockets, TLS, and an OS-style networking environment. So the right mental model is:

• good fit for embedded Linux / appliance software / networked devices with a real userspace
• not a blanket promise for tiny bare-metal microcontrollers

Why the public API uses snake_case

The naming style is deliberate.

The public API uses snake_case because it fits naturally with modern standard-library-adjacent C++ style and keeps names predictable:

• get_current_license
• set_panel_event_callback
• enable_panel_events

For a library that wants to feel like a natural tool in C++, boring and predictable naming is a feature, not a lack of creativity.

Summary

The philosophy is straightforward:

• give the host application real control
• return errors instead of performing UI theater
• stay portable and headless
• use modern, fast implementation technology internally
• keep the public API unsurprising for C++ developers

That is why the library looks the way it does.

Related pages

• Overview
• Callbacks and hooks
• Common pitfalls
• Session methods