Control Policies

Control Policies

Control policies restrict which control commands are allowed for a particular control API call path.

The policy mechanism exists so that powerful control commands can be reused safely from different sources. For example, startup environment control can allow level and trace changes while rejecting file backend changes.

---

Public API

#include <Logme/Logme.h>
#include <Logme/ControlPolicy.h>

std::string response = Logme::Instance->Control(
  "level --channel net debug",
  Logme::ControlPolicy::Safe()
);

The old overload remains available:

std::string response = Logme::Instance->Control("help");

It uses full control for backward compatibility.

---

Built-in policies

ControlPolicy::Full()

Allows the normal unrestricted control surface. This is the behavior of the original Logger::Control(command) overload and the compatibility default.

ControlPolicy::Safe()

Designed for conservative diagnostics. It allows:

• level changes
• output flag changes
• trace point commands
• subsystem filtering commands
• non-sensitive informational commands such as help/version/list/overview/channel inspection

It rejects:

• extension commands
• logs
• backend changes
• file backend changes
• channel creation/deletion
• channel routing changes
• error-channel changes

This is the default policy used by Environment Control.

ControlPolicy::Diagnostic()

Starts from Safe() and additionally allows backend changes.

The policy still keeps AllowFileBackends disabled by default, so it is intended for temporary diagnostic backends such as console, debugger, buffer, or ring buffer rather than arbitrary file output.

---

Custom policy

A policy object can be customized directly:

Logme::ControlPolicy policy = Logme::ControlPolicy::Diagnostic();
policy.AllowFileBackends = true;
policy.AllowLogsCommand = false;
policy.AllowExtensions = false;

std::string response = Logme::Instance->Control(command, policy);

Available switches include:

• AllowExtensions
• AllowLogsCommand
• AllowFormatCommand
• AllowFileBackends
• AllowChannelCreateDelete
• AllowChannelRouting
• AllowChannelError
• AllowBackendChanges
• AllowLevelChanges
• AllowFlagChanges
• AllowTraceChanges
• AllowSubsystemChanges

Use a custom policy when the built-in Safe, Diagnostic, and Full presets do not match the trust level of a command source.

---

Important behavior

Policy is checked before command execution. Extension commands are also subject to policy: if extensions are not allowed, the extension handler is not called.

Rejected commands return an error response and are logged through the normal internal diagnostics path when used by environment control.

Policy does not make a control command transactional. If a source executes several commands and a later command is rejected, earlier successful commands remain applied.

---

Relationship to control server

The policy-aware overload is a programmatic API. Existing control-server behavior is preserved for compatibility unless the application explicitly routes a command source through a policy-aware path.

Use Security and Control Server recommendations when exposing network control. Use Environment Control for startup overrides driven by environment variables.