How pixaranimationstudios/chook works
Project Type & Purpose
• Chook is a Ruby-based framework and gem that sets up a webhook handling server for Jamf Pro. It not only provides a sinatra-based HTTP(S) server to accept and process Jamf webhook POST requests (in JSON) but also supplies a modular framework for writing both internal (Ruby) and external (any language) event handlers.
• Its purpose is to abstract Jamf Pro webhook events into Ruby objects (events and subjects), manage event handling, and provide an admin interface for configuration and log viewing.
File Structure
• Top-level files such as README.md, LICENSE.txt, and CHANGES.md indicate standard gem packaging.
• The bin directory contains the chook-server executable used to launch the sinatra-based server.
• The data directory holds:
• A sample configuration file (e.g., chook.conf.example),
• A plist for LaunchDaemon,
• Sample event handler files (both executable and Ruby scripts),
• Sample JSON payloads for each event type.
• The lib directory contains the core Ruby source code:
• The main module definition (chook.rb),
• Submodules for configuration, event handling (e.g., event.rb, handled_event.rb),
• The server-specific code under lib/chook/server, including routes, authentication, logging, static public resources, and view templates.
• Namespaced classes for events and subjects indicating a clear separation of concerns in event processing.
• The presence of numerous subdirectories under lib/chook/ (e.g., event, server, subject) suggests the project adopts modular, layered design, possibly with patterns such as MVC and event-driven architecture.
Key Components
a. The HTTP(S) Server Component:
• Sinatra-based web server (launched via chook-server in the bin directory) with endpoints:
• /handle_webhook_event for processing incoming Jamf JSON POSTs.
• / (the admin interface) for monitoring logs, viewing handlers, and configuration.
• SSL configuration branch (noting use_ssl and relevant certificate/key configuration).
b. Core Framework & Event Handling:
• Chook Ruby module and its submodules (lib/chook) that encapsulate:
• Event parsing (Chook::Event and its subclasses)
• Event handling logic (internal handlers defined in Ruby, external handlers as executable files)
• The abstraction of Jamf Pro webhook events into Event and Subject objects.
• Separation between “HandledEvents” (for production use) and “TestEvents” (for simulation).
c. Configuration & Logging:
• A component for Server Configuration (with a node indicating /etc/chook.conf or falling back on defaults found in data/chook.conf.example).
d. Event Handler Directories:
• Differentiate internal handlers (non-executable Ruby files that register with Chook.event_handler) and external handlers (executable files that process raw JSON input).
Relations and Interactions
• Jamf Pro Server → (HTTP POST with JSON) → Chook’s /handle_webhook_event endpoint.
• Web Server → (JSON parsing via Chook::Event.parse_event) → Core framework (event and subject object creation).
• Core event handling → (invocation of internal Ruby blocks or external executable calls) → Custom handlers.
• Handlers → Logging component (either directly using event.logger or via an external logging endpoint).
• The Admin Interface → (HTTP GET/POST) → Server management functions (log streaming, handler reloading, config viewing).
• Separation of concerns: communication (networking), event processing, and administration.
Architectural Patterns & Technologies to Emphasize
• Event-Driven Architecture: The flow from receiving a webhook to processing via dynamically loaded handlers.
• Modular Design: The use of discrete namespaces (e.g., Chook::HandledEvents, Chook::TestEvents, Chook::Subjects) in the framework.
• MVC-like Aspects: While not a full MVC application, the sinatra server plays a role in managing web interactions (routes, views) and separating presentation (views in haml under lib/chook/server/views) from logic.
• Technologies in Use:
• Ruby and associated gems (sinatra, thin, eventmachine)
• For external handlers: the capability to work with any language (often using shell scripts and JSON tools like jq).