connect

Opens the websocket connection and selects a Blazeauth API server automatically.

connect opens the websocket connection for the current blaze::session. The library resolves a suitable server automatically and returns basic metadata about the selected server.

Function variants

blaze::api_server connect();
blaze::api_server connect(std::error_code& ec) noexcept;
void async_connect(std::function<void(std::error_code, blaze::api_server)> callback);
blaze::coro::awaitable_result<blaze::api_server> co_connect();

No API status here

connect does not return blaze::status. If connection setup fails, the failure is reported through std::error_code or std::system_error.

Result

struct api_server {
  std::string location;
};

Prop

Type

Behavior notes

connect opens the websocket transport and selects a server automatically.
After a successful connect, call initialize.
The returned location is informational. The library manages the actual connection endpoint internally.
After connect finishes, last_operation_took is updated with the measured connection/setup time, even if connect ends with an error.
Sync overloads use the session timeout configured in the constructor or via with_timeout(...).
Coroutine overloads are available only when the library is built with coroutine support.

Example

Compilation note

Synchronous and Asynchronous examples compile in the same form from C++17 to C++26.

#include "blazeauth/api/api.hpp"

#include <iostream>
#include <string>
#include <system_error>

void print_error_code(const std::string& context, const std::error_code& ec) {
  std::cout << context << ": " << ec.message() << " ("
            << ec.value() << " : " << ec.category().name() << ")\n";
}

int main() {
  blaze::session session;

  try {
    const blaze::api_server server = session.connect();

    std::cout << "Connected to server location: " << server.location << '\n';

    session.shutdown();
    std::cout << "Connection closed successfully\n";
  } catch (const std::system_error& e) {
    print_error_code("Connect failed", e.code());
    return 1;
  }

  return 0;
}

Error handling

You can match generic failures against blaze::errc, for example: if (ec == blaze::errc::service_unavailable).

Error condition	When it can happen
`already_connected`	`connect` was called on a session that is already connected.
`timed_out`	A sync overload exceeded the configured session timeout while waiting for completion.
`operation_would_block`	A sync overload was called from the library I/O thread.
`service_unavailable`	The balancer reported that no currently usable server could be selected.
`connection_lost`	Network or TLS transport failed while establishing the websocket session.
`protocol_error`	The balancer response or websocket handshake was not valid for the expected protocol.

Balancer-specific error codes

When you need more detail than generic blaze::errc, connect may also surface raw balancer-specific std::error_code values from blaze::error::balancer_error.

Balancer error	When it can happen
`internal_error`	Balancer failure did not map to a more specific public availability code.
`response_schema_mismatch`	Balancer returned JSON that did not match the schema expected by the library.
`no_servers_available`	Balancer has no usable servers to return.
`no_servers_online`	Matching servers exist, but none of them are currently online.
`no_servers_for_this_version`	No server is available for the API version used by this library.

connect

Function variantsCopy Anchor Link

ResultCopy Anchor Link

Behavior notesCopy Anchor Link

ExampleCopy Anchor Link

Error handlingCopy Anchor Link

Balancer-specific error codesCopy Anchor Link

Related pagesCopy Anchor Link