From 42602b0faac7b35ca47aaa655be71f45bb2f877d Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Jun 2025 00:23:54 +0000 Subject: [PATCH 1/6] Initial plan for issue From aef87576d05cee91097f03f23d80180999ee2507 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Jun 2025 00:26:10 +0000 Subject: [PATCH 2/6] Initial plan: Add detailed Mermaid flow diagram to README Co-authored-by: GrantBirki <23362539+GrantBirki@users.noreply.github.com> --- .bundle/config | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.bundle/config b/.bundle/config index 0146a1ce..f9263841 100644 --- a/.bundle/config +++ b/.bundle/config @@ -1,7 +1,8 @@ --- BUNDLE_BIN: "bin" -BUNDLE_PATH: "vendor/gems" +BUNDLE_PATH: "/home/runner/work/hooks/hooks/vendor/bundle" BUNDLE_CACHE_PATH: "vendor/cache" BUNDLE_CACHE_ALL: "true" BUNDLE_SPECIFIC_PLATFORM: "true" BUNDLE_NO_INSTALL: "true" +BUNDLE_DEPLOYMENT: "true" From 7ddaa1a2d6b6b965707cfde1eadedfd4ec323b0c Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Thu, 19 Jun 2025 00:27:44 +0000 Subject: [PATCH 3/6] Add comprehensive Mermaid flow diagram to README Co-authored-by: GrantBirki <23362539+GrantBirki@users.noreply.github.com> --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/README.md b/README.md index aa9d31ed..c4905d55 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,84 @@ Hooks is a RESTful webhook server framework written in Ruby. It is designed to b Hooks is designed to be very easy to setup and use. It provides a simple DSL for defining webhook endpoints and then you can use plugins to handle the incoming requests and optionally authenticate them. +### Architecture Flow + +The following Mermaid diagram shows the complete request processing flow, including server bootstrap, plugin loading, and webhook request handling: + +```mermaid +flowchart TD + A[Server Start] --> B[Builder.new] + B --> C[Load & Validate Config] + C --> D[Create Logger] + D --> E[Load All Plugins] + E --> F[Load Endpoints] + F --> G[Create Grape API] + G --> H[Server Ready] + + H --> I[Incoming Request] + I --> J[Generate Request ID] + J --> K[Create Request Context] + K --> L[Build Rack Environment] + L --> M[Lifecycle: on_request] + + M --> N{IP Filtering Enabled?} + N -->|Yes| O[Check IP Allow/Block Lists] + N -->|No| P[Enforce Request Limits] + O --> Q{IP Allowed?} + Q -->|No| R[Return 403 Forbidden] + Q -->|Yes| P + + P --> S[Read Request Body] + S --> T{Auth Required?} + T -->|Yes| U[Load Auth Plugin] + T -->|No| V[Parse Payload] + + U --> W[Validate Auth] + W --> X{Auth Valid?} + X -->|No| Y[Return 401/403 Error] + X -->|Yes| V + + V --> Z[Load Handler Plugin] + Z --> AA[Normalize Headers] + AA --> BB[Call Handler.call] + BB --> CC[Lifecycle: on_response] + CC --> DD[Log Success] + DD --> EE[Return 200 + Response] + + BB --> FF{Handler Error?} + FF -->|Hooks::Plugins::Handlers::Error| GG[Return Handler Error Response] + FF -->|StandardError| HH[Log Error] + HH --> II[Lifecycle: on_error] + II --> JJ[Return 500 + Error Response] + + R --> KK[End] + Y --> KK + GG --> KK + EE --> KK + JJ --> KK + + subgraph "Plugin Types" + LL[Auth Plugins
HMAC, Shared Secret, Custom] + MM[Handler Plugins
Process Webhook Payload] + NN[Lifecycle Plugins
on_request, on_response, on_error] + OO[Instrument Plugins
Stats, Failbot] + end + + subgraph "Configuration" + PP[Global Config
hooks.yml] + QQ[Endpoint Configs
Individual .yml files] + RR[Plugin Directories
Auth, Handlers, Lifecycle] + end + + style A fill:#e1f5fe + style H fill:#c8e6c9 + style R fill:#ffcdd2 + style Y fill:#ffcdd2 + style EE fill:#c8e6c9 + style JJ fill:#ffcdd2 + style GG fill:#fff3e0 +``` + Here is a very high-level overview of how Hooks works: 1. You define a global configuration file (e.g. `hooks.yml`) where you can specify where your webhook endpoint configs are located, and the directory where your plugins are located. Here is an example of a minimal configuration file: From ce73861222b07afe239c48ce6385c371326109ed Mon Sep 17 00:00:00 2001 From: GrantBirki Date: Wed, 18 Jun 2025 22:49:58 -0700 Subject: [PATCH 4/6] fix bundle --- .bundle/config | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.bundle/config b/.bundle/config index f9263841..0146a1ce 100644 --- a/.bundle/config +++ b/.bundle/config @@ -1,8 +1,7 @@ --- BUNDLE_BIN: "bin" -BUNDLE_PATH: "/home/runner/work/hooks/hooks/vendor/bundle" +BUNDLE_PATH: "vendor/gems" BUNDLE_CACHE_PATH: "vendor/cache" BUNDLE_CACHE_ALL: "true" BUNDLE_SPECIFIC_PLATFORM: "true" BUNDLE_NO_INSTALL: "true" -BUNDLE_DEPLOYMENT: "true" From ef316c9503e02b849407893b35bede90da10b941 Mon Sep 17 00:00:00 2001 From: GrantBirki Date: Wed, 18 Jun 2025 22:57:32 -0700 Subject: [PATCH 5/6] Refactor Mermaid diagram styles and remove redundant subgraphs for clarity --- README.md | 27 +++++++-------------------- 1 file changed, 7 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index c4905d55..a15ef6ac 100644 --- a/README.md +++ b/README.md @@ -82,26 +82,13 @@ flowchart TD EE --> KK JJ --> KK - subgraph "Plugin Types" - LL[Auth Plugins
HMAC, Shared Secret, Custom] - MM[Handler Plugins
Process Webhook Payload] - NN[Lifecycle Plugins
on_request, on_response, on_error] - OO[Instrument Plugins
Stats, Failbot] - end - - subgraph "Configuration" - PP[Global Config
hooks.yml] - QQ[Endpoint Configs
Individual .yml files] - RR[Plugin Directories
Auth, Handlers, Lifecycle] - end - - style A fill:#e1f5fe - style H fill:#c8e6c9 - style R fill:#ffcdd2 - style Y fill:#ffcdd2 - style EE fill:#c8e6c9 - style JJ fill:#ffcdd2 - style GG fill:#fff3e0 + style A fill:#035980 + style H fill:#027306 + style R fill:#a10010 + style Y fill:#a10010 + style EE fill:#027306 + style JJ fill:#a10010 + style GG fill:#915a01 ``` Here is a very high-level overview of how Hooks works: From 321e37ba1b66f0ff8c7835e6d4fb952b32aa4a56 Mon Sep 17 00:00:00 2001 From: GrantBirki Date: Wed, 18 Jun 2025 23:01:41 -0700 Subject: [PATCH 6/6] Add detailed Architecture Flow diagram to documentation --- README.md | 67 ++------------------------------------- docs/architecture_flow.md | 64 +++++++++++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 65 deletions(-) create mode 100644 docs/architecture_flow.md diff --git a/README.md b/README.md index a15ef6ac..7511024b 100644 --- a/README.md +++ b/README.md @@ -26,71 +26,6 @@ Hooks is a RESTful webhook server framework written in Ruby. It is designed to b Hooks is designed to be very easy to setup and use. It provides a simple DSL for defining webhook endpoints and then you can use plugins to handle the incoming requests and optionally authenticate them. -### Architecture Flow - -The following Mermaid diagram shows the complete request processing flow, including server bootstrap, plugin loading, and webhook request handling: - -```mermaid -flowchart TD - A[Server Start] --> B[Builder.new] - B --> C[Load & Validate Config] - C --> D[Create Logger] - D --> E[Load All Plugins] - E --> F[Load Endpoints] - F --> G[Create Grape API] - G --> H[Server Ready] - - H --> I[Incoming Request] - I --> J[Generate Request ID] - J --> K[Create Request Context] - K --> L[Build Rack Environment] - L --> M[Lifecycle: on_request] - - M --> N{IP Filtering Enabled?} - N -->|Yes| O[Check IP Allow/Block Lists] - N -->|No| P[Enforce Request Limits] - O --> Q{IP Allowed?} - Q -->|No| R[Return 403 Forbidden] - Q -->|Yes| P - - P --> S[Read Request Body] - S --> T{Auth Required?} - T -->|Yes| U[Load Auth Plugin] - T -->|No| V[Parse Payload] - - U --> W[Validate Auth] - W --> X{Auth Valid?} - X -->|No| Y[Return 401/403 Error] - X -->|Yes| V - - V --> Z[Load Handler Plugin] - Z --> AA[Normalize Headers] - AA --> BB[Call Handler.call] - BB --> CC[Lifecycle: on_response] - CC --> DD[Log Success] - DD --> EE[Return 200 + Response] - - BB --> FF{Handler Error?} - FF -->|Hooks::Plugins::Handlers::Error| GG[Return Handler Error Response] - FF -->|StandardError| HH[Log Error] - HH --> II[Lifecycle: on_error] - II --> JJ[Return 500 + Error Response] - - R --> KK[End] - Y --> KK - GG --> KK - EE --> KK - JJ --> KK - - style A fill:#035980 - style H fill:#027306 - style R fill:#a10010 - style Y fill:#a10010 - style EE fill:#027306 - style JJ fill:#a10010 - style GG fill:#915a01 -``` - Here is a very high-level overview of how Hooks works: 1. You define a global configuration file (e.g. `hooks.yml`) where you can specify where your webhook endpoint configs are located, and the directory where your plugins are located. Here is an example of a minimal configuration file: @@ -205,6 +140,8 @@ Congratulations! You have successfully set up a basic Hooks server which will li Keep reading to learn how to customize your Hooks server with different plugins for handlers, authentication, and more. +For an in-depth flow diagram of how the Hooks server processes incoming requests, see the [Architecture Flow](docs/architecture_flow.md) documentation. + ### Advanced This section will go into a more advanced and detailed example of how to setup a Hooks server with custom plugins, authentication, and more. This section also assumes you already have the `hooks-ruby` gem installed via a bundler Gemfile as shown in the [Installation](#installation-) section above. diff --git a/docs/architecture_flow.md b/docs/architecture_flow.md new file mode 100644 index 00000000..ff7a3122 --- /dev/null +++ b/docs/architecture_flow.md @@ -0,0 +1,64 @@ +# Architecture Flow + +The following Mermaid diagram shows the complete request processing flow, including server bootstrap, plugin loading, and webhook request handling: + +```mermaid +flowchart TD + A[Server Start] --> B[Builder.new] + B --> C[Load & Validate Config] + C --> D[Create Logger] + D --> E[Load All Plugins] + E --> F[Load Endpoints] + F --> G[Create Grape API] + G --> H[Server Ready] + + H --> I[Incoming Request] + I --> J[Generate Request ID] + J --> K[Create Request Context] + K --> L[Build Rack Environment] + L --> M[Lifecycle: on_request] + + M --> N{IP Filtering Enabled?} + N -->|Yes| O[Check IP Allow/Block Lists] + N -->|No| P[Enforce Request Limits] + O --> Q{IP Allowed?} + Q -->|No| R[Return 403 Forbidden] + Q -->|Yes| P + + P --> S[Read Request Body] + S --> T{Auth Required?} + T -->|Yes| U[Load Auth Plugin] + T -->|No| V[Parse Payload] + + U --> W[Validate Auth] + W --> X{Auth Valid?} + X -->|No| Y[Return 401/403 Error] + X -->|Yes| V + + V --> Z[Load Handler Plugin] + Z --> AA[Normalize Headers] + AA --> BB[Call Handler.call] + BB --> CC[Lifecycle: on_response] + CC --> DD[Log Success] + DD --> EE[Return 200 + Response] + + BB --> FF{Handler Error?} + FF -->|Hooks::Plugins::Handlers::Error| GG[Return Handler Error Response] + FF -->|StandardError| HH[Log Error] + HH --> II[Lifecycle: on_error] + II --> JJ[Return 500 + Error Response] + + R --> KK[End] + Y --> KK + GG --> KK + EE --> KK + JJ --> KK + + style A fill:#035980 + style H fill:#027306 + style R fill:#a10010 + style Y fill:#a10010 + style EE fill:#027306 + style JJ fill:#a10010 + style GG fill:#915a01 +```