Complete Feature Reference

Fluent builder API

ModelDefinition md("note", "slip_box");
md.set_group("Slip Box", 100)
  .set_all_rest_operations()     // C+R+U+D+L
  .set_title_column("title")
  .set_columns({
    {"title",     MANDATORY | TEXT},
    {"content",   TEXTAREA},
    {"map_id",    FOREIGN_KEY},  // auto → Integer
    {"parent_note_id", FOREIGN_KEY},
    {"is_public", BOOL | MUTABLE},
    {"importance", INTEGER}
  });

Every call returns ModelDefinition& for chaining. set_columns() automatically prepends id, created_at, updated_at as the first three columns.

All configuration options

Auto-inference rules

Type flags (mutually exclusive)

Behaviour flags (combinable)

Usage example

// Combine any flags with bitwise OR:
{"title",       MANDATORY | TEXT},
{"content",     TEXTAREA | MUTABLE},
{"parent_id",   FOREIGN_KEY | HIDDEN},
{"token_hash",  MANDATORY | UNIQUE | INTERNAL},
{"enabled",     BOOL | MUTABLE}
  .set_default_value(true)
  .set_description("Whether the job is active.")

Interface definition

class IValidator {
public:
  // Is the user allowed to create this record?
  virtual OperationResult can_create(
    DbPtr& db,
    AccessTokenContext& token,
    entity_fields& ef) const = 0;

  virtual OperationResult can_read(
    DbPtr& db,
    AccessTokenContext& token,
    identification id) const = 0;

  virtual OperationResult can_update(
    DbPtr& db,
    AccessTokenContext& token,
    entity_fields& ef,
    entity_fields& old_fields) const = 0;

  virtual OperationResult can_delete(
    DbPtr& db,
    AccessTokenContext& token,
    identification id) const = 0;

  virtual OperationResult can_list(
    DbPtr& db,
    AccessTokenContext& token,
    string_map& filter) const = 0;
};

OperationResult

struct OperationResult {
  int status;      // 0 = OK, 403/405/... = error
  std::string error; // human-readable reason

  bool ok() const { return status == 0; }
  bool ko() const { return !ok(); }
  explicit operator bool() const noexcept;
};

// Convenience macros:
ok_result {}
status_403_forbidden {403, "You are not authorized..."}
status_405_unsupported_operation {405, "..."}

AccessTokenContext

struct AccessTokenContext {
  identification user_id;
  std::string msg;
  int status;   // HTTP status: 200=ok, 401=...
  bool system;  // true = system token

  bool ok() const;
  bool is_system() const;
};

Validators use token.ok() to check authentication and token.user_id for ownership checks. Cross-model queries via IValidator::get_validator(model_name).

Core Plugin validators (13)

UserValidator, TeamValidator, TeamMemberValidator, HistoryValidator, ApiLogValidator, AccessTokenValidator, RefreshTokenValidator, LoginSessionValidator, AuthLogValidator, SuperAdminLogValidator, JobEntryValidator, JobRunValidator, ErrorValidator

Internal structure

// Fixed thread pool of 4 worker threads
class CronScheduler {
  struct ScheduledJobEntry {
    JobPtr  job;
    std::string cron;        // expression
    time_t  next_run;
    i64     job_id;          // job_entry.id
    std::string job_name;
    bool    enabled;
    bool    running;
    time_t  last_started_at;
    time_t  last_enabled_check;
    cronq::JobConfig job_config;
  };

  // Methods:
  void scheduler_loop();
  void load_jobs_from_db();
  void compute_initial_next_runs();
  void run_job(ScheduledJobEntry&);
  void insert_job_run();
  void update_job_run();
  void update_next_run_in_db();
};

Job class

class Job : public AbstractTriggerJob {
  Job(
    const std::string& job_name,
    const std::string& job_description,
    const std::string& cron_expression,
    bool enabled_by_default = true,
    bool run_once_when_missed = true
  );

  // Override to implement job logic:
  virtual std::string run(
    cronq::JobConfig& job_config) = 0;

  // Query access (same as Trigger):
  nlohmann::json call_query(
    const std::string& query_name,
    nlohmann::json& request);
};

JobConfig

// Access per-job configuration:
auto [val, err] = job_config.get_string("key");
auto val2 = job_config.get_int_or_default(
  "days", 30);
auto hash = job_config.get_sha256();
// (SHA-256 of entire config content)

Cache characteristics

• Algorithm: LRU (Least Recently Used)
• TTL: 1 week by default (set_ttl_ms())
• Capacity by count: 10 000 entries (read_cache_capacity_size)
• Capacity by bytes: 1 GB (read_cache_capacity_bytes)
• Thread-safe: std::shared_mutex (shared reads, exclusive writes)
• Key: CacheKey { table_name, record_id }

Stats tracked

struct CacheStats {
  size_t hits;
  size_t misses;
  size_t evicted_lru;   // evicted by LRU policy
  size_t expired;       // evicted by TTL
  size_t shrinks;       // forced shrinks
};

Cache API

class ModelCache {
  // Read from cache (shared lock):
  bool get(table, id, out_row);

  // Write to cache (exclusive lock):
  void put(table, id, row);

  // Invalidate on update/delete:
  void invalidate(table, id);

  // Full flush:
  void clear();

  // Force-shrink to target size:
  void shrink_to(size_t target, ByteUnit);

  // Configuration:
  void set_ttl_ms(int64_t ms);
  void set_capacity_size(size_t n);
  void set_capacity_bytes(size_t bytes);

  // Diagnostics:
  void print_info();
  CacheStats information_no_lock() const;
};

Cache is disabled per-model via ModelDefinition::set_cache_enabled(false). Disabled automatically for frequently-written models like api_log, history.

Token lifecycle

Security details

• Tokens stored as SHA-256 hash (via OpenSSL), never plaintext
• Token rotation: refresh token replaced when remaining lifetime < rotation threshold
• Revocation: is_revoked flag + revoked_at timestamp per token
• refresh_token.replaced_by_id and rotated_from_id maintain rotation chain
• Login session links access token + refresh token in login_session table
• Token purpose: Session / Api / Service

Auth endpoints

// Login — returns access + refresh tokens
POST /api/v1/auth/login
{
  "username": "admin",
  "password": "secret"
}
// Response:
{
  "user_id": 1,
  "access_token": "...",
  "access_token_expires_at": 1234567890,
  "refresh_token": "..."
}

// Refresh (proactive in frontend: 60s before expiry)
POST /api/v1/auth/refresh_token
{ "refresh_token": "..." }

// Logout
POST /api/v1/auth/logout
Authorization: Bearer <access_token>
{ "refresh_token": "..." }

// Change password
POST /api/v1/auth/change_password
{ "old_password": "...",
  "new_password": "..." }

// Register
POST /api/v1/auth/register
{ "username": "...", "password": "...",
  "email": "..." }

enum UserRole {
  Guest     = 0,   // unauthenticated
  Reader    = 1,   // read-only
  Editor    = 2,   // can create/update
  Reviewer  = 3,   // can review
  Admin     = 4,   // full control
  SuperAdmin= 5,   // platform admin
  System    = 100  // internal system user
};

enum UserStatus {
  Pending     = 0,  // awaiting approval
  Active      = 1,  // normal access
  Deactivated = 2,  // soft-disabled
  Banned      = 3,  // policy violation
  Suspended   = 4,  // temporary
  Deleted     = 5   // logical delete
};

enum RegistrationMode {
  Free                  = 0,
  RequiresAdminApproval = 1,
  AdminAddsUsers        = 2
};

File naming format

// Regex: V(\d+)__([a-zA-Z0-9_]+)\.sql
// Example names:
V1__create_user.sql
V2__create_team.sql
V13__add_job_entry_configuration.sql

// Migrations stored as C++ raw string
// literals inline in MigrationScripts.cpp

Integrity checks

• Each migration carries a SHA-256 checksum of its SQL content
• A chain hash is computed over the ordered sequence of all checksums
• Both are verified at startup — any modification to an applied migration causes startup failure
• Migrations are applied transactionally: failure rolls back cleanly
• Applied migrations tracked in the migration table

Multi-database readiness

The Core plugin already ships two migration script implementations:

• CoreSQLiteMigrationScripts — V1–V14 in SQLite dialect
• CorePostgreSQLMigrationScripts — V1–V14 in PostgreSQL dialect

This signals active work toward multi-DB support via the planned IDatabase / IStatement / IMigration interface layer (see Roadmap).

Migration counts