Rix Documentation

This example shows how to register a user, log in, and authenticate a session with rix/auth.

The example uses the public Rix facade:

cpp

#include <rix.hpp>

and accesses auth through:

cpp

rix.auth

It uses an in-memory auth store, so it is useful for examples, tests, and local development.

Create the file

bash

mkdir -p ~/rix-auth-memory-example
cd ~/rix-auth-memory-example
touch memory_register_login.cpp

Add:

cpp

#include <rix.hpp>

int main()
{
  rix.debug.print("== rix/auth memory register and login ==");

  auto auth = rix.auth.memory();

  auto registered = auth.register_user({
      "ada@example.com",
      "correct-password"});

  if (registered.failed())
  {
    const auto &error = registered.error();

    rix.debug.eprint(
        "auth error:",
        rix.auth.error.to_string(error),
        error.message());

    return 1;
  }

  rix.debug.print("registered user");
  rix.debug.print("id:", registered.value().id());
  rix.debug.print("email:", registered.value().email());

  auto login = auth.login({
      "ada@example.com",
      "correct-password"});

  if (login.failed())
  {
    const auto &error = login.error();

    rix.debug.eprint(
        "auth error:",
        rix.auth.error.to_string(error),
        error.message());

    return 1;
  }

  rix.debug.print("----------------------------------------");
  rix.debug.print("login successful");
  rix.debug.print("user:", login.value().user.email());
  rix.debug.print("session:", login.value().session.id());
  rix.debug.print("token issuer:", login.value().token.issuer());

  auto session = auth.authenticate_session(
      login.value().session.id());

  if (session.failed())
  {
    const auto &error = session.error();

    rix.debug.eprint(
        "auth error:",
        rix.auth.error.to_string(error),
        error.message());

    return 1;
  }

  rix.debug.print("----------------------------------------");
  rix.debug.print("OK:", "session authenticated");
  rix.debug.print("session user id:", session.value().user_id());

  return 0;
}

Run it:

bash

vix run memory_register_login.cpp

If Rix is not available yet for single-file usage:

bash

vix install -g rix/rix
vix run memory_register_login.cpp

Expected output shape:

txt

== rix/auth memory register and login ==
registered user
id: user_...
email: ada@example.com
----------------------------------------
login successful
user: ada@example.com
session: session_...
token issuer: rix/auth
----------------------------------------
OK: session authenticated
session user id: user_...

What this example does

The example creates an auth service with memory stores:

cpp

auto auth = rix.auth.memory();

It registers a user:

cpp

auto registered = auth.register_user({
    "ada@example.com",
    "correct-password"});

It logs the user in:

cpp

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

It authenticates the created session:

cpp

auto session = auth.authenticate_session(
    login.value().session.id());

Memory auth

rix.auth.memory() creates an auth service backed by in-memory user and session stores.

cpp

auto auth = rix.auth.memory();

This is useful for:

txt

examples
tests
local development
small demos
temporary applications

Memory auth does not persist users or sessions after the process exits.

For real applications that need durable users and sessions, use a database-backed store.

Register a user

Use:

cpp

auto registered = auth.register_user({
    "ada@example.com",
    "correct-password"});

The first field is the email.

The second field is the plain-text password.

The password is hashed before storage.

The plain-text password should not be logged.

Check registration errors

register_user returns a result.

Check the result before using the user:

cpp

if (registered.failed())
{
  const auto &error = registered.error();

  rix.debug.eprint(
      "auth error:",
      rix.auth.error.to_string(error),
      error.message());

  return 1;
}

Then access the created user:

cpp

const auto &user = registered.value();

Read the registered user

cpp

rix.debug.print("id:", registered.value().id());
rix.debug.print("email:", registered.value().email());

A user has:

txt

id
email
password hash
email verification state
active state
timestamps

Do not print the password hash in application output.

Log in

Use:

cpp

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

On success, login returns:

txt

user
session
token

Access them with:

cpp

login.value().user
login.value().session
login.value().token

cpp

if (login.failed())
{
  const auto &error = login.error();

  rix.debug.eprint(
      "auth error:",
      rix.auth.error.to_string(error),
      error.message());

  return 1;
}

A login can fail when the user does not exist, the password is wrong, the user is disabled, or email verification is required by the configuration.

cpp

rix.debug.print("user:", login.value().user.email());
rix.debug.print("session:", login.value().session.id());
rix.debug.print("token issuer:", login.value().token.issuer());

The session id and token value are sensitive.

In production, do not log raw session ids or token values.

The example prints the session id only to make the flow visible.

Authenticate a session

Use:

cpp

auto session = auth.authenticate_session(
    login.value().session.id());

If the session exists, is not revoked, and is not expired, the result succeeds.

cpp

if (session.ok())
{
  rix.debug.print("session user id:", session.value().user_id());
}

Check session errors

cpp

if (session.failed())
{
  const auto &error = session.error();

  rix.debug.eprint(
      "auth error:",
      rix.auth.error.to_string(error),
      error.message());

  return 1;
}

A session can fail authentication when it is missing, expired, revoked, or invalid.

Complete flow

The normal memory auth flow is:

txt

create auth service
register user
login user
authenticate session
handle errors explicitly

In code:

cpp

auto auth = rix.auth.memory();

auto registered = auth.register_user({
    "ada@example.com",
    "correct-password"});

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

auto session = auth.authenticate_session(
    login.value().session.id());

In real code, check each result before using value().

Error handling pattern

Use this pattern for auth operations:

cpp

auto result = auth.login({
    "ada@example.com",
    "correct-password"});

if (result.failed())
{
  const auto &error = result.error();

  rix.debug.eprint(
      "auth error:",
      rix.auth.error.to_string(error),
      error.message());

  return 1;
}

Then use:

cpp

result.value()

Only after checking success.

Duplicate registration example

This example shows a failed registration when the same email is used twice.

cpp

#include <rix.hpp>

int main()
{
  auto auth = rix.auth.memory();

  auto first = auth.register_user({
      "ada@example.com",
      "correct-password"});

  if (first.failed())
  {
    return 1;
  }

  auto second = auth.register_user({
      "ada@example.com",
      "correct-password"});

  if (second.failed())
  {
    rix.debug.eprint(
        "expected auth error:",
        rix.auth.error.to_string(second.error()),
        second.error().message());

    return 0;
  }

  return 1;
}

Run:

bash

vix run memory_register_login.cpp

The second registration should fail because the user already exists.

Wrong password example

cpp

#include <rix.hpp>

int main()
{
  auto auth = rix.auth.memory();

  auto registered = auth.register_user({
      "ada@example.com",
      "correct-password"});

  if (registered.failed())
  {
    return 1;
  }

  auto login = auth.login({
      "ada@example.com",
      "wrong-password"});

  if (login.failed())
  {
    rix.debug.eprint(
        "expected auth error:",
        rix.auth.error.to_string(login.error()),
        login.error().message());

    return 0;
  }

  return 1;
}

This should fail with an invalid credentials error.

Use a custom memory configuration

You can pass an auth configuration to memory.

cpp

auto config = rix.auth.config.development();

config.set_min_password_length(8);
config.set_token_ttl_seconds(60 * 15);
config.set_session_ttl_seconds(60 * 60 * 24 * 7);

auto auth = rix.auth.memory(config);

Use this when the default behavior needs to be changed for an example or application.

Production-like memory config

For stricter rules:

cpp

auto config = rix.auth.config.production();

auto auth = rix.auth.memory(config);

Production configuration requires email verification before login.

For this example, development configuration is simpler because it allows login immediately after registration.

Use in a Vix project

Create a project:

bash

vix new rix-auth-memory --app
cd rix-auth-memory

Add Rix:

bash

vix add rix/rix
vix install

Make sure vix.app contains:

txt

deps = [
  "rix/rix",
]

A minimal vix.app can look like this:

txt

name = "rix-auth-memory"
type = "executable"
standard = "c++20"
output_dir = "bin"

sources = [
  "src/main.cpp",
]

include_dirs = [
  "include",
  "src",
]

deps = [
  "rix/rix",
]

packages = [
  "vix",
]

links = [
  "vix::vix",
]

Put the example code in:

txt

src/main.cpp

Build and run:

bash

vix build
vix run

Single-file usage

For examples, tests, and quick experiments:

bash

vix run memory_register_login.cpp

If needed:

bash

vix install -g rix/rix
vix run memory_register_login.cpp

For project usage, prefer:

bash

vix add rix/rix
vix install

and keep the dependency in vix.app:

txt

deps = [
  "rix/rix",
]

Use only auth with the facade

If you want the rix.* facade style but only want auth mounted, define the feature macro before including rix.hpp:

cpp

#define RIX_ENABLE_AUTH
#include <rix.hpp>

int main()
{
  auto auth = rix.auth.memory();

  auto registered = auth.register_user({
      "ada@example.com",
      "correct-password"});

  return registered.ok() ? 0 : 1;
}

When at least one RIX_ENABLE_* macro is defined, only selected modules are mounted.

If you also want debug output:

cpp

#define RIX_ENABLE_AUTH
#define RIX_ENABLE_DEBUG
#include <rix.hpp>

int main()
{
  auto auth = rix.auth.memory();

  auto registered = auth.register_user({
      "ada@example.com",
      "correct-password"});

  if (registered.failed())
  {
    rix.debug.eprint(
        "auth error:",
        rix.auth.error.to_string(registered.error()),
        registered.error().message());

    return 1;
  }

  rix.debug.print("registered:", registered.value().email());
  return 0;
}

Use the independent package

For independent usage, install:

bash

vix add rix/auth
vix install

In vix.app:

txt

deps = [
  "rix/auth",
]

Then include auth package headers directly.

The examples in this documentation prefer the public facade:

cpp

#include <rix.hpp>

and:

cpp

rix.auth

Common mistakes

Forgetting to install Rix

If rix.hpp is not found, install Rix first.

For a project:

bash

vix add rix/rix
vix install

For single-file usage:

bash

vix install -g rix/rix

Putting Rix in `packages`

Wrong:

txt

packages = [
  "rix/rix",
]

Correct:

txt

deps = [
  "rix/rix",
]

deps is for Vix Registry packages.

packages is for CMake package discovery.

Calling `value()` before checking success

Wrong:

cpp

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

rix.debug.print(login.value().user.email());

Correct:

cpp

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

if (login.failed())
{
  return 1;
}

rix.debug.print(login.value().user.email());

Using production config without verifying email

This can fail:

cpp

auto auth = rix.auth.memory(
    rix.auth.config.production());

auto registered = auth.register_user({
    "ada@example.com",
    "correct-password"});

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

Production config requires email verification before login.

For the simple memory example, use:

cpp

auto auth = rix.auth.memory();

Printing sensitive values in production

Avoid printing:

txt

plain-text passwords
password hashes
raw tokens
session ids

The example prints the session id only to make the flow understandable.

In production, avoid logging it.

Expecting memory auth to persist data

Memory auth is not durable.

When the process exits, users and sessions are gone.

Use database-backed stores for real applications.

What you should remember

Create a memory auth service:

cpp

auto auth = rix.auth.memory();

cpp

auto registered = auth.register_user({
    "ada@example.com",
    "correct-password"});

cpp

auto login = auth.login({
    "ada@example.com",
    "correct-password"});

Authenticate a session:

cpp

auto session = auth.authenticate_session(
    login.value().session.id());

Check errors before using values:

cpp

if (login.failed())
{
  rix.debug.eprint(
      "auth error:",
      rix.auth.error.to_string(login.error()),
      login.error().message());

  return 1;
}

For project usage:

bash

vix add rix/rix
vix install

and keep:

txt

deps = [
  "rix/rix",
]

Next step

Continue with password hashing.

Next: Password hashing

Memory Register and Login ​

Create the file ​

What this example does ​

Memory auth ​

Register a user ​

Check registration errors ​

Read the registered user ​

Log in ​

Check login errors ​

Read login result ​

Authenticate a session ​

Check session errors ​

Complete flow ​

Error handling pattern ​

Duplicate registration example ​

Wrong password example ​

Use a custom memory configuration ​

Production-like memory config ​

Use in a Vix project ​

Single-file usage ​

Use only auth with the facade ​

Use the independent package ​

Common mistakes ​

Forgetting to install Rix ​

Putting Rix in packages ​

Calling value() before checking success ​

Using production config without verifying email ​

Printing sensitive values in production ​

Expecting memory auth to persist data ​

What you should remember ​

Next step ​

Memory Register and Login

Create the file

What this example does

Memory auth

Register a user

Check registration errors

Read the registered user

Log in

Check login errors

Read login result

Authenticate a session

Check session errors

Complete flow

Error handling pattern

Duplicate registration example

Wrong password example

Use a custom memory configuration

Production-like memory config

Use in a Vix project

Single-file usage

Use only auth with the facade

Use the independent package

Common mistakes

Forgetting to install Rix

Putting Rix in `packages`

Calling `value()` before checking success

Using production config without verifying email

Printing sensitive values in production

Expecting memory auth to persist data

What you should remember

Next step