Home /Modules/web-server-technology/envelopment.h

envelopment.h

web-server-technology/native/envelopment.h · 109 line(s) · c

#ifndef SLEELA_WST_ENVELOPMENT_H
#define SLEELA_WST_ENVELOPMENT_H
/*
 * web-server-technology/native/envelopment.h
 *
 * The envelopment model -- Side 2 of the web server interface.
 *
 * Side 1 (always on): a program goes to a domain and then a meme. One domain
 * resolves to a single coherent response unit. The base server
 * (dyn_sql_server.cpp) implements this directly.
 *
 * Side 2 (this file, opt-in, Scientist-gated): a domain may carry many
 * subjects/warrants for causes, so the website becomes an ENVELOPMENT of many
 * disparate programs behind one domain. A warrant binds a cause to a subject
 * (a host/path matcher) and a program (what runs). Envelopment resolution maps
 * an incoming (host, path) to exactly one program; the base dispatch then runs
 * that program's backing kind (static subtree, SQL surface, or a fixed meme).
 *
 * This module is deliberately self-contained and transport-agnostic: it knows
 * nothing about sockets or HTTP wire format. It is only a model plus a resolver
 * plus a config loader, so it can be unit-tested in isolation and so that the
 * base server never depends on it when envelopment is disabled.
 */
#include <string>
#include <vector>

namespace sleela {
namespace wst {

/* The backing behaviour a program provides when its warrant is selected. */
enum class ProgramKind {
  Static,  /* serve files from a document-root subtree          */
  Sql,     /* expose a /db-style SQL surface over a table dir    */
  Meme     /* return a single fixed response (the "meme")        */
};

/* A named, mounted unit of behaviour. */
struct Program {
  std::string name;        /* unique program name within the envelopment     */
  ProgramKind kind = ProgramKind::Meme;
  std::string mount;       /* path prefix this program owns, e.g. "/a"        */
  std::string root;        /* Static: document root subtree                   */
  std::string db_dir;      /* Sql: directory of CSV tables                    */
  bool db_writable = false;/* Sql: whether mutations are permitted            */
  std::string meme_type;   /* Meme: content-type (default text/plain)         */
  std::string meme_body;   /* Meme: the fixed response body                   */
};

/* A warrant: a cause served for a subject by a program. The "subject" is the
 * match key -- a host (and optional path prefix) under which the cause holds. */
struct Warrant {
  std::string cause;       /* the reason-to-serve, free text (logged)         */
  std::string subject;     /* host to match, e.g. "science.example"; "*" = any*/
  std::string path_prefix; /* optional additional path gate, "" = any         */
  std::string program;     /* name of the Program this warrant activates      */
  bool enabled = true;     /* a disabled warrant never matches                */
};

/* One domain's envelopment: its programs and the warrants that route to them.*/
struct Envelopment {
  bool enabled = false;      /* master switch (Side 2 off => Side 1 only)     */
  bool scientist = false;    /* capability gate: envelopment requires this    */
  std::string domain;        /* the domain this envelopment fronts            */
  std::vector<Program> programs;
  std::vector<Warrant> warrants;

  /* Look up a program by name; nullptr if absent. */
  const Program *find_program(const std::string &name) const;

  /* Is envelopment usable? Requires enabled AND scientist AND >=1 warrant. */
  bool active() const;

  /*
   * Resolve an incoming request to a program. Returns the selected Program and
   * sets out_cause to the matched warrant's cause, or nullptr if no enabled
   * warrant matches (the caller then falls back to Side-1 dispatch). Matching
   * is: subject == host (or "*"), AND path starts with path_prefix (or ""),
   * first enabled warrant in declaration order wins.
   */
  const Program *resolve(const std::string &host, const std::string &path,
                         std::string &out_cause) const;
};

/* Human-readable kind name, for status/diagnostics. */
const char *program_kind_name(ProgramKind k);

/*
 * Load an envelopment from a config file. The format is a tiny, line-oriented
 * key/value grammar (see docs/ENVELOPMENT.md); '#' begins a comment. Unknown
 * keys are ignored so the same file can also configure the base server.
 * Returns true on a successful parse (even if envelopment stays disabled).
 * On a hard error (unreadable file, malformed required field) returns false
 * and fills err.
 */
bool load_envelopment_config(const std::string &path, Envelopment &out,
                             std::string &err);

/*
 * Apply a single "key=value" setting to an envelopment (used by both the config
 * loader and startup-flag overrides so CLI and file share one code path).
 * Returns false and fills err on a malformed directive.
 */
bool apply_envelopment_setting(const std::string &key, const std::string &value,
                               Envelopment &out, std::string &err);

}  // namespace wst
}  // namespace sleela
#endif  // SLEELA_WST_ENVELOPMENT_H