# Gogs Webhook Server

A modular Node.js server for receiving and processing Gogs webhooks. The server logs all incoming webhooks to the console and provides an extensible callback system for custom event handling.

## Features

- **Modular Architecture**: Clean separation of concerns (server, handler, logger)
- **Extensible Callback System**: Register callbacks for specific events or all events
- **Console Logging**: Colored, formatted logging of all webhook events
- **Health Check Endpoint**: Built-in health monitoring
- **Graceful Shutdown**: Proper cleanup on process termination
- **Zero Dependencies**: Pure Node.js implementation

## Requirements

- Node.js >= 18.0.0

## Installation

```bash
npm install
```

## Usage

### Basic Usage (Logging Only)

Start the server with default configuration:

```bash
npm start
```

The server will start on port 3000 and log all incoming webhooks to the console.

### Development Mode (Auto-reload)

```bash
npm run dev
```

### Configuration

Configure the server using environment variables:

```bash
PORT=8080 WEBHOOK_PATH=/gogs WEBHOOK_SECRET=your-secret npm start
```

Available environment variables:
- `PORT`: Server port (default: 3000)
- `WEBHOOK_PATH`: Webhook endpoint path (default: /webhook)
- `WEBHOOK_SECRET`: Optional webhook secret for signature verification

### Endpoints

- `POST /webhook` - Webhook endpoint
- `GET /health` - Health check endpoint

## Extending with Callbacks

The server is designed to be easily extended with custom callbacks. See `examples/with-callbacks.js` for a complete example.

### Register Event-Specific Callbacks

```javascript
import { WebhookServer } from './src/server.js';

const server = new WebhookServer({ port: 3000 });
const handler = server.getHandler();

// Handle push events
handler.on('push', async (payload, headers) => {
  console.log('Push to:', payload.repository.name);
  console.log('Commits:', payload.commits.length);
  // Your custom logic here
});

// Handle pull request events
handler.on('pull_request', async (payload, headers) => {
  console.log('PR:', payload.action);
  // Your custom logic here
});

server.start();
```

### Register Global Callbacks

```javascript
// Handle all events
handler.onAny(async (eventType, payload, headers) => {
  console.log('Received event:', eventType);
  // Send to analytics, external logging, etc.
});
```

### Run the Example

```bash
node examples/with-callbacks.js
```

## Gogs Webhook Configuration

1. Go to your Gogs repository settings
2. Navigate to Webhooks → Add Webhook → Gogs
3. Configure:
   - **Payload URL**: `http://your-server:3000/webhook`
   - **Content Type**: `application/json`
   - **Secret**: (optional) your webhook secret
   - **Events**: Select which events to receive
4. Click "Add Webhook"

### Supported Events

- `push` - Repository push
- `create` - Branch or tag creation
- `delete` - Branch or tag deletion
- `pull_request` - Pull request actions
- `issues` - Issue actions
- `issue_comment` - Issue comment actions
- `release` - Release actions

## Project Structure

```
.
├── src/
│   ├── index.js           # Main entry point
│   ├── server.js          # HTTP server implementation
│   ├── webhookHandler.js  # Webhook processing and callbacks
│   └── logger.js          # Logging utility
├── examples/
│   └── with-callbacks.js  # Example with custom callbacks
├── package.json
└── README.md
```

## Architecture

### WebhookServer (`src/server.js`)
- Creates HTTP server
- Handles routing and request parsing
- Manages webhook verification
- Delegates webhook processing to handler

### WebhookHandler (`src/webhookHandler.js`)
- Manages callback registration
- Executes callbacks for events
- Supports event-specific and global callbacks
- Provides error handling for callbacks

### Logger (`src/logger.js`)
- Formats and colorizes console output
- Provides structured logging methods
- Handles timestamp formatting

## Testing

You can test the webhook server using curl:

```bash
# Test health check
curl http://localhost:3000/health

# Test webhook with push event
curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -H "X-Gogs-Event: push" \
  -H "X-Gogs-Delivery: 12345" \
  -d '{
    "ref": "refs/heads/main",
    "repository": {
      "name": "test-repo",
      "full_name": "user/test-repo"
    },
    "pusher": {
      "username": "testuser"
    },
    "commits": [
      {
        "id": "abc123",
        "message": "Test commit"
      }
    ]
  }'
```

## License

ISC