set_session

set_session_value(std::string key, std::string content, std::chrono::seconds ttl) stores a value under key in the current session cache and returns blaze::status.

Function variants

blaze::status set_session_value(std::string key, std::string content, std::chrono::seconds ttl);
blaze::status set_session_value(std::string key, std::string content, std::chrono::seconds ttl, std::error_code& ec) noexcept;
void async_set_session_value(
  std::string key,
  std::string content,
  std::chrono::seconds ttl,
  std::function<void(std::error_code, blaze::status)> callback
);
blaze::coro::awaitable_result<blaze::status> co_set_session_value(std::string key, std::string content, std::chrono::seconds ttl);

Status vs error

The returned blaze::status is the API result. std::error_code and std::system_error are used for transport/runtime failures only.

Parameters

Prop

Type

Result

blaze::status

Use direct comparison, for example:

if (status == blaze::status::ok) {
  // success
}

Behavior notes

Call set_session_value only after successful connect and initialize.
This is session-scoped volatile storage attached to the current websocket session.
Values are not shared across sessions.
Writing an existing key overwrites its content and refreshes its TTL.
Use delete_session_value if you need to remove an entry before its TTL expires.
This method does not provide a built-in default TTL. You pass ttl explicitly on every call.
If ttl <= 0s, the request still sends that value and the server applies its own default TTL of 72h.
Current server-side limits for this cache are 64 entries and 16384 bytes of total stored values per session.

Example

Compilation note

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

#include "blazeauth/api/api.hpp"

#include <chrono>
#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";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

void print_status(const std::string& context, blaze::status status) {
  std::cout << context << ": "
            << static_cast<unsigned int>(status)
            << " (" << blaze::to_string(status) << ")\n";
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string key = read_line("Session key");
  const std::string value_content = read_line("Session value");

  blaze::session session;

  try {
    const blaze::api_server server = session.connect();
    std::cout << "Connected to server location: " << server.location << '\n';

    const blaze::application app = session.initialize(websocket_api_key, client_id);
    if (!app.good()) {
      print_status("Initialize returned status", app.status);
      return 1;
    }

    const blaze::status set_status = session.set_session_value(key, value_content, std::chrono::hours(1));
    if (set_status != blaze::status::ok) {
      print_status("Set-session-value returned status", set_status);
      return 1;
    }

    std::cout << "Session value stored successfully\n";
    session.shutdown();
  } catch (const std::system_error& e) {
    print_error_code("Set-session-value failed", e.code());
    return 1;
  }

  return 0;
}

#include "blazeauth/api/api.hpp"

#include <chrono>
#include <future>
#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";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

void print_status(const std::string& context, blaze::status status) {
  std::cout << context << ": "
            << static_cast<unsigned int>(status)
            << " (" << blaze::to_string(status) << ")\n";
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string key = read_line("Session key");
  const std::string value_content = read_line("Session value");

  blaze::session session;

  std::promise<int> completion;
  std::future<int> result = completion.get_future();

  session.async_connect(
    [&session, &completion, websocket_api_key, client_id, key, value_content](std::error_code connect_ec, blaze::api_server server) mutable {
      if (connect_ec) {
        print_error_code("Connect failed", connect_ec);
        completion.set_value(1);
        return;
      }

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

      session.async_initialize(websocket_api_key, client_id,
        [&session, &completion, key, value_content](std::error_code init_ec, blaze::application app) mutable {
          if (init_ec) {
            print_error_code("Initialize failed", init_ec);
            completion.set_value(1);
            return;
          }

          if (!app.good()) {
            print_status("Initialize returned status", app.status);
            completion.set_value(1);
            return;
          }

          session.async_set_session_value(key, value_content, std::chrono::hours(1),
            [&session, &completion](std::error_code set_ec, blaze::status set_status) {
              if (set_ec) {
                print_error_code("Set-session-value failed", set_ec);
                completion.set_value(1);
                return;
              }

              if (set_status != blaze::status::ok) {
                print_status("Set-session-value returned status", set_status);
                completion.set_value(1);
                return;
              }

              std::cout << "Session value stored successfully\n";

              session.async_shutdown([&completion](std::error_code shutdown_ec) {
                if (shutdown_ec) {
                  print_error_code("Shutdown failed", shutdown_ec);
                  completion.set_value(1);
                  return;
                }

                completion.set_value(0);
              });
            });
        });
    });

  return result.get();
}

Project must be built with C++20 support and with coroutine support available both in the language mode and in the standard library implementation for this example to compile correctly.

#include "blazeauth/api/api.hpp"

#include <chrono>
#include <future>
#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";
}

std::string read_line(const std::string& label) {
  std::string value;
  std::cout << label << ": ";
  std::getline(std::cin, value);
  return value;
}

#if BLAZEAUTH_HAS_COROUTINES

blaze::coro::task<std::error_code> run_example(
  blaze::session& session,
  const std::string& websocket_api_key,
  const std::string& client_id,
  const std::string& key,
  const std::string& content,
  std::chrono::seconds ttl
) {
  const auto [connect_ec, server] = co_await session.co_connect();
  if (connect_ec) {
    co_return connect_ec;
  }

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

  const auto [init_ec, app] = co_await session.co_initialize(websocket_api_key, client_id);
  if (init_ec) {
    co_return init_ec;
  }

  if (!app.good()) {
    co_return blaze::make_error_code(app.status);
  }

  const auto [set_ec, set_status] = co_await session.co_set_session_value(key, content, ttl);
  if (set_ec) {
    co_return set_ec;
  }

  if (set_status != blaze::status::ok) {
    co_return blaze::make_error_code(set_status);
  }

  std::cout << "Session value stored successfully\n";

  const auto [shutdown_ec] = co_await session.co_shutdown();
  co_return shutdown_ec;
}

int main() {
  const std::string websocket_api_key = read_line("Websocket API key");
  const std::string client_id = read_line("Client ID");
  const std::string key = read_line("Session key");
  const std::string value_content = read_line("Session value");

  blaze::session session;

  std::promise<std::error_code> completion;
  std::future<std::error_code> result = completion.get_future();

  blaze::coro::co_spawn([&session, &completion, websocket_api_key, client_id, key, value_content]() mutable
                          -> blaze::coro::task<void> {
    const std::error_code ec = co_await run_example(session, websocket_api_key, client_id, key, value_content, std::chrono::hours(1));
    completion.set_value(ec);
    co_return;
  }());

  const std::error_code ec = result.get();
  if (ec) {
    print_error_code("Set-session-value failed", ec);
    return 1;
  }

  return 0;
}

#else

int main() {
  std::cout << "This example requires coroutine support in the Blazeauth library build.\n";
  return 0;
}

#endif

Set-session-value statuses

Value	Status	Returned when
`1`	`ok`	Value was stored successfully.
`701`	`store_out_of_memory`	Session cache memory limit was exceeded for this write.
`702`	`store_out_of_entries`	Session cache entry limit was exceeded for this write.

Connection-level shutdowns

Normal set-session-value results are returned as blaze::status. The websocket may still be closed by session-level guards:

Close code	Meaning	When it can happen
`4200`	`not_initialized`	`set_session_value` was called before a successful `initialize`.
`4201`	`rate_limited`	Session or IP rate limiting closed the websocket around this operation.

set_session_value

On this page