Warlock Overview

Warlock is the application server component of the Hazaar MVC framework. It extends the framework's capabilities beyond the standard request-response lifecycle, enabling real-time communication, background processing, and persistent services.

Architecture

Warlock uses a distributed architecture consisting of two main components: the Server and the Agent. These components communicate via a dedicated protocol to coordinate tasks and data flow.

Warlock Server

The Warlock Server acts as the central hub and message broker. Because it is independent of application logic, it does not require an application context to run. It simply needs a configuration file defining ports and other server settings.

It is responsible for:

• Real-Time Signalling: Routing messages between clients (browsers), the application backend, and services. It supports WebSockets and standard sockets.
• Key/Value Store (KVStore): Hosting an in-memory database for shared state across the application.
• Connection Management: Managing connections from Agents, Services, and WebSocket clients.

The Server typically runs on port 8000 (default) and listens for incoming connections.

• Configuration: Configured via warlock.json.
• Command: warlock run -c app/configs/warlock.json

Warlock Agent

The Warlock Agent is the worker process responsible for executing application code. Because it executes your code, it requires an application context. You must provide the path to your application when starting the Agent.

Since the Server is designed to be lightweight and non-blocking, it delegates heavy lifting and PHP code execution to the Agent. The Agent handles:

• Delayed Execution: Running code in the background (e.g., sending emails, processing uploads) to keep the frontend responsive.
• Services: Managing long-running background processes (daemons).
• Event Handling: Spawning short-lived processes to react to specific events triggered within the system.

The Agent processes tasks from a queue and manages the lifecycle of service processes. It connects to the Server to receive instructions and report status.

• Configuration: Configured via agent.json.
• Command: warlock agent run -p /path/to/app

Communication

The Server and Agent communicate using the Hazaar\Warlock\Protocol over a TCP connection. This allows them to run on the same machine or be distributed across a network.

Distributed Messaging

Warlock servers can be configured to form a network, allowing multiple servers to communicate and distribute messages across a larger system. This enables the creation of "hub" architectures where messages triggered on one server can be propagated to clients connected to other servers in the cluster.

Note

While messaging is distributed, direct code execution (e.g., delayed jobs or specific service calls) is strictly local to the Agent connected to the server that received the request. However, Event Handlers are an exception: triggering an event will cause all subscribed Agents across the entire distributed network to execute their handlers.

Features at a Glance

Feature	Component	Description
Real-Time Signalling	Server	Instant messaging between server, services, and browser clients (WebSockets).
Key/Value Store	Server	Fast, in-memory shared storage for data persistence across processes.
Distributed Messaging	Server	Create distributed hubs to propagate messages across multiple servers.
Delayed Execution	Agent	Execute code asynchronously in the background.
Services	Agent	Create persistent, long-running background applications.
Event Handlers	Agent	React to global events with dedicated, short-lived processes.

Getting Started

To use Warlock, you typically need to start both the Server and at least one Agent.

# Start the Server (requires configuration file)
vendor/bin/warlock run -c app/configs/warlock.json

# Start the Agent (requires application path)
vendor/bin/warlock agent run -p /path/to/app

Refer to the specific feature documentation for detailed usage instructions.