Extensibility through Event Hooks

[grovesy]

Summary

Organizational deployments of Git Proxy often need to run organization-specific integrations before and after Git Proxy actions are performed, such as clone, pull, and push.

Examples include:

• integration with internal request or approval systems
• fine-grained entitlement system integrations
• chat or notification integrations
• organization-specific scanners or processing hooks

Proposal

Introduce a simple, lightweight, and well-abstracted event system that external integrations can hook into.

These interfaces should be abstracted from Git Proxy internals and should expose only the logical operations Git Proxy is performing. This would allow organizations to extend behavior without coupling directly to internal workflow or chain implementation details.

Example

A simple example of an email handler:

proxy
  .registerEventHandler()
  .onPull()
  .onCompleted(myEmailHandler);

async function myEmailHandler(repo: RepositoryContext, user: UserContext): Promise<void> {
  // Check whether this is the user's first pull of the repository
  if (await isFirstPull(repo, user)) {
    const emailBody = `
Welcome to Git Proxy.

Here is everything you need to get started before submitting your first push request...
`;

    await email.send(user.emailAddress, "Getting started with Git Proxy", emailBody);
  }
}

Proposed API

interface IProxyEventRegistry {
  onPull(): IActionEventHandler;
  onClone(): IActionEventHandler;
  onPush(): IActionEventHandler;
}

interface IActionEventHandler {
  onStarted(handler: ActionEventCallback): IActionEventHandler;
  onCompleted(handler: ActionEventCallback): IActionEventHandler;
  onError(handler: ActionErrorEventCallback): IActionEventHandler;
  onPermissionDenied(handler: ActionEventCallback): IActionEventHandler;
}

type ActionEventCallback = (
  repo: RepositoryContext,
  user: UserContext
) => void | Promise<void>;

type ActionErrorEventCallback = (
  repo: RepositoryContext,
  user: UserContext,
  error: Error
) => void | Promise<void>;

Notes

While the existing chain could theoretically be modified to insert additional actions, that approach is cumbersome and invasive because it requires integrations to hook directly into the core execution flow of Git Proxy.

That would make future workflow refactoring significantly harder, since external users would then become dependent on internal chain handler interfaces and execution semantics.

A dedicated event model would provide a cleaner extension point, with lower coupling and a clearer contract for organizational integrations.

[re-vlad]

Thank you for the proposal. While reviewing it, I noticed a few design gaps and wanted to suggest a possible alternative approach. Two design questions seem important before implementation starts:

1. Are event handlers required to be asynchronous?
2. If synchronous execution is allowed, what guarantees exit about blocking the git response?

The proposal does not currently state whether event handlers must process events asynchronously. This is an important design decision because it directly affects the responsibilities and safety guarantees of the extension mechanism.

Based on the proposal, the two extension mechanisms appear to serve different purposes:

• Chain plugins — validation, policy enforcement, and any logic that must be able to block or modify the operation.
• Event handlers — notifications, logging, metrics, and integrations with external systems that should observe outcomes without influencing them.

In this model, event handlers do not need to synchronize with the git response. They simply react to the outcome of the operation independently.

[re-vlad]

1. Synchronous execution (blocking contract ?)

If event processing is synchronous, the proposal does not define whether handlers may delay the git response to the user. The described code provides no clear place to express blocking vs non-blocking semantics. However, this decision has direct safety implications for every git operation that passes through the proxy.

Alsor there is question to where events are emitted in the request flow:

A. Emit from inside executeChain's finally block (outside the processor loop)
B. Emit from proxyFilter after executeChain returns

Since, onStarted must be emitted from inside executeChain, immediately after parseAction succeeds (chain.ts line 55). This means that onStarted and the terminal events cannot share a single emission point.

One straightforward implementation would emit all events from inside executeChain and rely on handlers not blocking the response. (which is not garanteed)

[re-vlad]

2. Asynchronous alternative solution (intent persistence)

A different architectural approach could avoid invoking external integrations directly from the processing chain. The pattern commonly called as 'transaction outbox'.

Instead of calling event handlers directly from the chain:
A. The chain writes a lightweight intent record to the database at defined lifecycle points.
B. A separate consumer reads those records and performs external calls asynchronously.

In this model, the chain’s only external responsibility is a short database write, while external integrations are handled outside the request path.

This approach properties:

• Handlers are optional. If none are registered for a given event, the record can simply be marked processed.
• Organizations could enable intent persistence purely for a durable audit trail and add handlers later without git-proxy infrastructure changes.

The git-proxy could ship with simple built-in handlers (e.g., one that logs events to the console). The survives process restarts: records written before a crash can be processed when git-proxy restarts and can be scaled horizontly. The consumer could run even as a separate application with independent scaling and failure domains.
Organizations with existing event infrastructure (message queues, workflow engines, etc.) could disable the built-in consumer and integrate their own processing pipeline.

If this approach is considered acceptable, it may be useful to propose the consumer configuration and handler API in a follow-up design discussion.

[re-vlad]

3. Handler error isolation is undefined
The proposal does not describe what happens when a registered handler throws or rejects. If a failure propagates upward, a broken notification integration can abort a legitimate git push. If failures are swallowed silently, integrators have no visibility into misbehaving handlers.
Please isolate all handlers from the main flow. Catch failures, log them with sufficient context to diagnose, and never propagate them to the git response.

4. No handler registration mechanism at startup

The proposal shows a runtime fluent API for registering handlers but does not explain how handler modules are loaded when Git-Proxy starts. Without a defined loading path, deployers have no way to attach handlers persistently across process restarts.
I suggest to add an eventHandlers configuration key following the same pattern as the existing plugins key.