# brahma-adshonor/gohook architecture

> Architecture diagram of the GitHub repository brahma-adshonor/gohook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brahma-adshonor/gohook
- Repository: https://github.com/brahma-adshonor/gohook

## Overview

##### Main Components
- Library API Layer: Represent the core exported functions (Hook, UnHook, HookByIndirectJmp, HookMethod, UnHookMethod) as the public interface. This is the primary entry point for consumers.
- Function Address Discovery: A component that employs the standard reflect library to obtain function addresses.
- Code Injection Engine: The module or set of functions (for instance, the routines in arch_util.go, elf_helper.go, hook.go) that craft and inject the jump instructions. This module is engineering the “hot patching” technique.
- Trampoline Mechanism: A dedicated module or routine (as seen in the examples and trampoline functions) that forms a “shadow” copy of the original function, enabling callbacks.
- Platform Specific Utilities: Highlight the use of utility files tailored to different OSes (utility_darwin.go, utility_linux.go, utility_unix.go, utility_windows.go). This indicates that the hooking process is sensitive to operating system specifics.
- Build & CI/CD Pipelines: Acknowledge the presence of GitHub workflows (.github/workflows/go.yml), azure-pipelines.yml, and perhaps even bug.sh. They are not runtime components but are key for ensuring integrity across multiple environments.

- Calculation/Gathering of CPU/ABI-critical data (possibly implemented with guidance from arch_util.go and elf_helper.go).
- Branching to either a direct jump or an indirect jump approach (the latter handling closures and reflect.MakeFunc() cases via HookByIndirectJmp).
- Parallel to code injection, indicate the creation/setup of the “Trampoline Function”. This sub-module holds a copy of the original function to allow callbacks.

##### Architectural Patterns and Design Principles
- It utilizes dynamic reflection and binary patching which can be considered “runtime instrumentation.”
- For testability and ease of integration, clearly segregate the test harness and example implementations.
- Use annotations for important caveats (like inlining risks or 32-bit limitations) which are mentioned in the README as side notes.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Main Flow
    Client["Client Application"]:::clientStyle
    API["Library API Layer\n(Hook, UnHook, HookByIndirectJmp, HookMethod, UnHookMethod)"]:::apiStyle
    AddressDiscovery["Function Address Discovery"]:::coreStyle
    Injection["Code Injection Engine"]:::coreStyle
    Trampoline["Trampoline Mechanism"]:::coreStyle
    PlatformUtilities["Platform Specific Utilities"]:::platform
    TestingHarness["Testing and Example Harness"]:::test
    BuildPipeline["Build & CI/CD Pipelines"]:::build

    Client -->|"calls"| API
    API -->|"calls-address"| AddressDiscovery
    AddressDiscovery -->|"finds-target"| Injection
    Injection -->|"injects jump"| Trampoline
    Trampoline -->|"returns-original"| API
    Injection -.->|"OS-handling"| PlatformUtilities
    API ---|"tested-by"| TestingHarness
    API ---|"verified-by"| BuildPipeline

    %% Function Address Discovery Details
    subgraph "Function Address Discovery Modules"
        AD_A["arch_util.go"]:::helperStyle
        AD_E["elf_helper.go"]:::helperStyle
        AddressDiscovery --> AD_A
        AddressDiscovery --> AD_E
    end

    %% Code Injection Engine Details
    subgraph "Code Injection Engine Modules"
        CI_A["arch_util.go"]:::helperStyle
        CI_E["elf_helper.go"]:::helperStyle
        CI_H["hook.go"]:::helperStyle
        Injection --> CI_A
        Injection --> CI_E
        Injection --> CI_H
    end

    %% Platform Specific Utilities Details
    subgraph "Platform Utilities Files"
        PS_D["utility_darwin.go"]:::platform
        PS_L["utility_linux.go"]:::platform
        PS_U["utility_unix.go"]:::platform
        PS_W["utility_windows.go"]:::platform
    end

    %% Testing and Example Harness Details
    subgraph "Testing and Example Files"
        EX_A["example/example.go"]:::test
        EX_B["example/example2.go"]:::test
        EX_C["example/example3.go"]:::test
        EX_Main["example/main.go"]:::test
        EX_Unwind["example/unwind.go"]:::test
        TS_FS["func_stack_test.go"]:::test
        TS_H["hook_test.go"]:::test
        TS_IF["inplace_fix_test.go"]:::test
        TS_INST["inst_fix_test.go"]:::test
        TS_SF["small_func_test.go"]:::test
    end

    %% Build & CI/CD Pipelines Details
    subgraph "Build & CI/CD Files"
        CI_Workflow[".github/workflows/go.yml"]:::build
        CI_Azure["azure-pipelines.yml"]:::build
        CI_Bug["bug.sh"]:::build
    end

    %% Click Events
    click API "https://github.com/brahma-adshonor/gohook/blob/master/hook.go"
    click AD_A "https://github.com/brahma-adshonor/gohook/blob/master/arch_util.go"
    click AD_E "https://github.com/brahma-adshonor/gohook/blob/master/elf_helper.go"
    click CI_A "https://github.com/brahma-adshonor/gohook/blob/master/arch_util.go"
    click CI_E "https://github.com/brahma-adshonor/gohook/blob/master/elf_helper.go"
    click CI_H "https://github.com/brahma-adshonor/gohook/blob/master/hook.go"
    click PS_D "https://github.com/brahma-adshonor/gohook/blob/master/utility_darwin.go"
    click PS_L "https://github.com/brahma-adshonor/gohook/blob/master/utility_linux.go"
    click PS_U "https://github.com/brahma-adshonor/gohook/blob/master/utility_unix.go"
    click PS_W "https://github.com/brahma-adshonor/gohook/blob/master/utility_windows.go"
    click EX_A "https://github.com/brahma-adshonor/gohook/blob/master/example/example.go"
    click EX_B "https://github.com/brahma-adshonor/gohook/blob/master/example/example2.go"
    click EX_C "https://github.com/brahma-adshonor/gohook/blob/master/example/example3.go"
    click EX_Main "https://github.com/brahma-adshonor/gohook/blob/master/example/main.go"
    click EX_Unwind "https://github.com/brahma-adshonor/gohook/blob/master/example/unwind.go"
    click TS_FS "https://github.com/brahma-adshonor/gohook/blob/master/func_stack_test.go"
    click TS_H "https://github.com/brahma-adshonor/gohook/blob/master/hook_test.go"
    click TS_IF "https://github.com/brahma-adshonor/gohook/blob/master/inplace_fix_test.go"
    click TS_INST "https://github.com/brahma-adshonor/gohook/blob/master/inst_fix_test.go"
    click TS_SF "https://github.com/brahma-adshonor/gohook/blob/master/small_func_test.go"
    click CI_Workflow "https://github.com/brahma-adshonor/gohook/blob/master/.github/workflows/go.yml"
    click CI_Azure "https://github.com/brahma-adshonor/gohook/blob/master/azure-pipelines.yml"
    click CI_Bug "https://github.com/brahma-adshonor/gohook/blob/master/bug.sh"

    %% Styles
    classDef clientStyle fill:#FFE0B2,stroke:#E65100,stroke-width:2px;
    classDef apiStyle fill:#BBDEFB,stroke:#0D47A1,stroke-width:2px;
    classDef coreStyle fill:#C8E6C9,stroke:#1B5E20,stroke-width:2px;
    classDef helperStyle fill:#E1F5FE,stroke:#01579B,stroke-width:2px;
    classDef platform fill:#F8BBD0,stroke:#880E4F,stroke-width:2px;
    classDef test fill:#FFF9C4,stroke:#F57F17,stroke-width:2px;
    classDef build fill:#D1C4E9,stroke:#4A148C,stroke-width:2px;
```
