### Start Test Server for Webhooks Source: https://github.com/cased/hubproxy/blob/main/README.md Run `go run internal/cmd/dev/testserver/main.go` to start a simple HTTP server that logs received webhooks. This is typically started by `dev.sh`. ```bash # Start on default port 8082 go run internal/cmd/dev/testserver/main.go ``` ```bash # Start on custom port go run internal/cmd/dev/testserver/main.go --port 8083 ``` -------------------------------- ### Start Development Environment Source: https://context7.com/cased/hubproxy/llms.txt Use the dev.sh script to start the complete development environment, including the test server and proxy. A custom webhook secret can be provided using the HUBPROXY_WEBHOOK_SECRET environment variable. ```bash ./tools/dev.sh ``` ```bash HUBPROXY_WEBHOOK_SECRET=my-secret ./tools/dev.sh ``` -------------------------------- ### Start HubProxy with SQLite Source: https://context7.com/cased/hubproxy/llms.txt Use this command to start HubProxy with SQLite for development. Ensure the HUBPROXY_WEBHOOK_SECRET environment variable is set. ```bash # Set webhook secret and start with SQLite (development) export HUBPROXY_WEBHOOK_SECRET="your-github-webhook-secret" hubproxy --db sqlite:hubproxy.db --target-url "http://your-service:8080/webhook" ``` -------------------------------- ### HubProxy Configuration Example (YAML) Source: https://github.com/cased/hubproxy/blob/main/README.md Example YAML configuration file for HubProxy. Demonstrates settings for webhook secrets, target URLs, log levels, IP validation, and database connections. ```yaml # Read webhook secret from file webhook-secret: file:/run/credentials/hubproxy-webhook-secret # Target URL to forward webhooks to target-url: "http://your-service:8080/webhook" # Log level (debug, info, warn, error) log-level: info # Validate that requests come from GitHub IPs validate-ip: true # Tailscale configuration (optional) # enable-tailscale: true # ts-authkey: "" # ts-hostname: hubproxy # Database configuration db: sqlite:hubproxy.db # db: mysql://user:pass@host/db ``` -------------------------------- ### Start HubProxy with MySQL Source: https://context7.com/cased/hubproxy/llms.txt Set up HubProxy for production with MySQL. Provide the database connection string and the target URL for forwarding webhooks. ```bash # Production with MySQL hubproxy --db "mysql://user:password@tcp(localhost:3306)/hubproxy" \ --target-url "http://your-service:8080/webhook" ``` -------------------------------- ### Start HubProxy with PostgreSQL Source: https://context7.com/cased/hubproxy/llms.txt Configure HubProxy for production use with PostgreSQL. The database connection string and target URL are required. ```bash # Production with PostgreSQL hubproxy --db "postgres://user:password@localhost:5432/hubproxy?sslmode=disable" \ --target-url "http://your-service:8080/webhook" \ --validate-ip=true ``` -------------------------------- ### Start HubProxy with Configuration File Source: https://context7.com/cased/hubproxy/llms.txt Launch HubProxy using a YAML configuration file. The webhook secret can be set via environment variable. ```bash # Start with config file export HUBPROXY_WEBHOOK_SECRET="your-secret-here" hubproxy --config config.yaml ``` -------------------------------- ### Start Development Environment Source: https://github.com/cased/hubproxy/blob/main/README.md Use `tools/dev.sh` to set up a development environment with a SQLite database and test server. Customize the webhook secret or test server port using environment variables or flags. ```bash # Start the development environment (required before using other tools) ./tools/dev.sh ``` ```bash # Customize webhook secret HUBPROXY_WEBHOOK_SECRET=my-secret ./tools/dev.sh ``` ```bash # Customize test server port ./tools/dev.sh --target-port 8083 ``` -------------------------------- ### HubProxy Configuration File Example Source: https://context7.com/cased/hubproxy/llms.txt Example YAML configuration file for HubProxy. Supports webhook secret from file, target URL, log level, IP validation, Tailscale, and database settings. ```yaml # config.yaml # Read webhook secret from file (useful for Docker secrets) webhook-secret: file:/run/credentials/hubproxy-webhook-secret # Target URL to forward webhooks to target-url: "http://your-service:8080/webhook" # Log level (debug, info, warn, error) log-level: info # Validate that requests come from GitHub IPs validate-ip: true # Tailscale configuration (optional) # enable-tailscale: true # ts-authkey: "" # ts-hostname: hubproxy # Database configuration db: sqlite:hubproxy.db # db: mysql://user:pass@host/db # db: postgres://user:pass@host/db ``` -------------------------------- ### Start HubProxy with Tailscale Integration Source: https://context7.com/cased/hubproxy/llms.txt Enable Tailscale integration for secure network access. Requires authentication key and hostname configuration. ```bash # With Tailscale for secure public access hubproxy --enable-tailscale --ts-authkey="ts-abc123..." --ts-hostname=hubproxy \ --db sqlite:hubproxy.db --target-url "http://your-service:8080/webhook" ``` -------------------------------- ### Replay Events Response Example (REST API) Source: https://github.com/cased/hubproxy/blob/main/README.md Example JSON response when replaying events via the REST API. Includes the count of replayed events and a list of event details. ```json { "replayed_count": 5, "events": [ { "id": "d2a1f85a-delivery-id-123-replay-abc123", "type": "push", "payload": { "ref": "refs/heads/main", "before": "6113728f27ae82c7b1a177c8d03f9e96e0adf246", "after": "76ae82c7b1a177c8d03f9e96e0adf2466113728f", "repository": { "full_name": "owner/repo", "private": false }, "pusher": { "name": "username", "email": "user@example.com" } }, "created_at": "2024-02-06T00:00:00Z", "forwarded_at": null, "repository": "owner/repo", "sender": "username", "replayed_from": "d2a1f85a-delivery-id-123" }, ... ] } ``` -------------------------------- ### Run Query with Statistics Source: https://context7.com/cased/hubproxy/llms.txt Execute the query tool with statistics enabled. No specific setup required beyond having the tool available. ```bash go run internal/cmd/dev/query/main.go --stats ``` -------------------------------- ### Querying Events with Storage Options Source: https://github.com/cased/hubproxy/blob/main/README.md Demonstrates how to query stored webhook events using various options such as event types, repository, time range, and forwarding status. Includes examples for listing all events, only replayed events, and original events that have been replayed. ```go // List all events events, err := storage.ListEvents(QueryOptions{ Types: []string{"push", "pull_request"}, Repository: "owner/repo", Since: time.Now().Add(-24 * time.Hour), Forwarded: true, }) ``` ```go // List only replayed events events, err := storage.ListEvents(QueryOptions{ Forwarded: false, }) ``` ```go // List original events that have been replayed events, err := storage.ListEvents(QueryOptions{ HasReplayedEvents: true, }) ``` -------------------------------- ### Get Event Statistics API Response Example Source: https://github.com/cased/hubproxy/blob/main/README.md JSON response structure for the /api/stats endpoint, showing counts for different event types. ```json { "push": 50, "pull_request": 25, "issues": 10 } ``` -------------------------------- ### Run Test Server Standalone Source: https://context7.com/cased/hubproxy/llms.txt Start the test server on a specific port to receive forwarded webhooks. Useful for local testing and debugging. ```bash go run internal/cmd/dev/testserver/main.go --port 8082 ``` -------------------------------- ### Query Webhook Events in PostgreSQL Source: https://github.com/cased/hubproxy/blob/main/README.md Example SQL queries for finding pull requests affecting specific files and tracking deployment frequency. These demonstrate the rich querying capabilities provided by using a database as a canonical store. ```sql -- Find PRs affecting specific files (PostgreSQL example) SELECT repository, payload->>'action', created_at FROM events WHERE type = 'pull_request' AND json_extract(payload, '$.pull_request.changed_files.filename') = 'critical.js'; -- Track deployment frequency (works in all databases) SELECT date(created_at), count(*) FROM events WHERE type = 'deployment' GROUP BY 1; ``` -------------------------------- ### GET /metrics Source: https://github.com/cased/hubproxy/blob/main/README.md Exposes Prometheus metrics for monitoring application performance and behavior. ```APIDOC ## GET /metrics ### Description Exposes Prometheus metrics endpoint for monitoring the application's performance and behavior. The metrics endpoint provides standard Go metrics including: - Webhook events counts for IP blocks, signature errors, stored and forwarded counts - HTTP request counts and errors - Go runtime metrics (memory usage, garbage collection, goroutines) ``` -------------------------------- ### Start HubProxy with Different Databases Source: https://github.com/cased/hubproxy/blob/main/README.md Configure HubProxy to use SQLite (default for development), PostgreSQL, or MySQL for event storage by specifying the database connection string. ```bash hubproxy --db sqlite:.cache/hubproxy.db ``` ```bash hubproxy --db "postgres://user:password@localhost:5432/hubproxy?sslmode=disable" ``` ```bash hubproxy --db "mysql://user:password@tcp(localhost:3306)/hubproxy" ``` -------------------------------- ### Get Event Statistics Since Specific Time Source: https://context7.com/cased/hubproxy/llms.txt Fetch event statistics starting from a particular timestamp. Use RFC3339 format for the 'since' parameter. ```bash # Get statistics since a specific time curl "http://localhost:8081/api/stats?since=2024-02-01T00:00:00Z" ``` -------------------------------- ### Get Webhook Event Statistics Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Obtain statistics for webhook events, aggregated by type, starting from a specified date and time. ```graphql query { stats(since: "2023-01-01T00:00:00Z") { type count } } ``` -------------------------------- ### Start HubProxy in Log-only Mode Source: https://context7.com/cased/hubproxy/llms.txt Run HubProxy in a mode that only stores events without forwarding them to a target URL. Useful for auditing or debugging. ```bash # Log-only mode (no forwarding, just stores events) hubproxy --db sqlite:hubproxy.db ``` -------------------------------- ### Replay Single Event API Response Example Source: https://github.com/cased/hubproxy/blob/main/README.md JSON response structure for replaying an event, including details of the replayed event and its origin. ```json { "id": "d2a1f85a-delivery-id-123-replay-abc123", "type": "push", "payload": { "ref": "refs/heads/main", "before": "6113728f27ae82c7b1a177c8d03f9e96e0adf246", "after": "76ae82c7b1a177c8d03f9e96e0adf2466113728f", "repository": { "full_name": "owner/repo", "private": false }, "pusher": { "name": "username", "email": "user@example.com" } }, "created_at": "2024-02-06T00:00:00Z", "forwarded_at": null, "repository": "owner/repo", "sender": "username", "replayed_from": "d2a1f85a-delivery-id-123" } ``` -------------------------------- ### Go Storage Interface Operations Source: https://context7.com/cased/hubproxy/llms.txt Programmatically interact with HubProxy's storage using the Go interface. This includes initializing the storage, creating schemas, listing events with various filters, retrieving single events, getting statistics, and marking events as forwarded. ```go package main import ( "context" "time" "hubproxy/internal/storage" "hubproxy/internal/storage/sql" ) func main() { ctx := context.Background() // Initialize storage store, err := sql.New("sqlite:hubproxy.db") if err != nil { panic(err) } defer store.Close() // Create schema if err := store.CreateSchema(ctx); err != nil { panic(err) } // List events with filters events, total, err := store.ListEvents(ctx, storage.QueryOptions{ Types: []string{"push", "pull_request"}, Repository: "owner/repo", Since: time.Now().Add(-24 * time.Hour), Limit: 50, Offset: 0, }) // Get only non-forwarded events (pending delivery) pendingEvents, _, err := store.ListEvents(ctx, storage.QueryOptions{ OnlyNonForwarded: true, }) // Get a single event by ID event, err := store.GetEvent(ctx, "d2a1f85a-delivery-id-123") // Get event statistics stats, err := store.GetStats(ctx, time.Now().Add(-24 * time.Hour)) // Returns: map[string]int64{"push": 50, "pull_request": 25} // Mark an event as forwarded err = store.MarkForwarded(ctx, "d2a1f85a-delivery-id-123") } ``` -------------------------------- ### List Webhook Events API Response Example Source: https://github.com/cased/hubproxy/blob/main/README.md JSON response structure for the /api/events endpoint, containing a list of events and the total count. ```json { "events": [ { "id": "d2a1f85a-delivery-id-123", "type": "push", "headers": { "X-GitHub-Event": ["push"], "X-GitHub-Delivery": ["d2a1f85a-delivery-id-123"], "X-Hub-Signature-256": ["sha256=..."] }, "payload": { "ref": "refs/heads/main", "before": "6113728f27ae82c7b1a177c8d03f9e96e0adf246", "after": "76ae82c7b1a177c8d03f9e96e0adf2466113728f", "repository": { "full_name": "owner/repo", "private": false }, "pusher": { "name": "username", "email": "user@example.com" } }, "created_at": "2024-02-06T00:00:00Z", "forwarded_at": "2024-02-06T00:00:01Z", "repository": "owner/repo", "sender": "username" } ], "total": 100 } ``` -------------------------------- ### Nginx Configuration for API Security with Basic Auth Source: https://github.com/cased/hubproxy/blob/main/README.md Example Nginx configuration to secure the HubProxy API using SSL and HTTP Basic Authentication. Ensure the .htpasswd file is properly configured. ```nginx server { listen 443 ssl; server_name api.hubproxy.example.com; ssl_certificate /path/to/cert.pem; ssl_certificate_key /path/to/key.pem; location / { auth_basic "HubProxy API"; auth_basic_user_file /etc/nginx/.htpasswd; proxy_pass http://localhost:8081; } } ``` -------------------------------- ### Get Event Statistics Source: https://context7.com/cased/hubproxy/llms.txt Retrieve counts of different webhook event types. By default, statistics are for the last 24 hours. ```bash # Get statistics for the last 24 hours (default) curl "http://localhost:8081/api/stats" ``` -------------------------------- ### GET /api/events Source: https://context7.com/cased/hubproxy/llms.txt Retrieves a list of webhook events with support for filtering and pagination. ```APIDOC ## GET /api/events ### Description Query webhook events with filtering and pagination support. ### Method GET ### Endpoint /api/events ### Query Parameters - **type** (string) - Optional - Filter by event type (e.g., `push`, `pull_request`). - **repository** (string) - Optional - Filter by repository in the format `owner/repo`. - **sender** (string) - Optional - Filter by the username of the event sender. - **since** (string) - Optional - Filter events created after this RFC3339 timestamp. - **until** (string) - Optional - Filter events created before this RFC3339 timestamp. - **limit** (integer) - Optional - The maximum number of events to return (default: 50). - **offset** (integer) - Optional - The number of events to skip for pagination. ### Response #### Success Response (200) - **events** (array) - An array of webhook event objects. - **id** (string) - Unique identifier for the event delivery. - **type** (string) - The type of the GitHub event. - **headers** (object) - The original headers of the webhook request. - **payload** (object) - The payload of the webhook event. - **created_at** (string) - Timestamp when the event was created (RFC3339). - **forwarded_at** (string) - Timestamp when the event was forwarded to the target URL (RFC3339), null if not forwarded. - **repository** (string) - The repository where the event occurred (format: `owner/repo`). - **sender** (string) - The username of the event sender. - **total** (integer) - The total number of events matching the query. #### Response Example ```json { "events": [ { "id": "d2a1f85a-delivery-id-123", "type": "push", "headers": {"X-GitHub-Event": ["push"], "X-GitHub-Delivery": ["d2a1f85a-delivery-id-123"]}, "payload": {"ref": "refs/heads/main", "repository": {"full_name": "owner/repo"}}, "created_at": "2024-02-06T00:00:00Z", "forwarded_at": "2024-02-06T00:00:01Z", "repository": "owner/repo", "sender": "username" } ], "total": 100 } ``` ``` -------------------------------- ### Get Prometheus Metrics Source: https://context7.com/cased/hubproxy/llms.txt Retrieve Prometheus metrics from the /metrics endpoint for monitoring HubProxy's performance and operational status. Key metrics include signature errors, stored events, blocked IPs, and forwarding success/errors. ```bash curl "http://localhost:8081/metrics" ``` -------------------------------- ### Get Event Statistics API Request Source: https://github.com/cased/hubproxy/blob/main/README.md HTTP GET request to retrieve statistics for webhook events. Can be filtered by a start time. ```http GET /api/stats ``` -------------------------------- ### Run All Tests Source: https://github.com/cased/hubproxy/blob/main/README.md Execute all tests using `make test`. For specific packages, use `go test ./path/...`. ```bash # Run all tests make test ``` ```bash # Run specific package tests go test ./internal/storage/... go test ./internal/webhook/... ``` ```bash # Run with race detection go test -race ./... ``` -------------------------------- ### GET /api/stats Source: https://context7.com/cased/hubproxy/llms.txt Retrieves statistics on webhook event counts. ```APIDOC ## GET /api/stats ### Description Retrieve event type counts for monitoring and analytics. ### Method GET ### Endpoint /api/stats ### Query Parameters - **since** (string) - Optional - Filter statistics for events created after this RFC3339 timestamp. Defaults to the last 24 hours. ### Response #### Success Response (200) - **(object)** - An object where keys are event types and values are their counts. #### Response Example ```json { "push": 50, "pull_request": 25, "issues": 10, "issue_comment": 8, "create": 5 } ``` ``` -------------------------------- ### Development Tools Source: https://context7.com/cased/hubproxy/llms.txt Utilize development tools for setting up the environment, simulating webhook events, and querying stored data. ```APIDOC ## Development Tools ### Description Provides command-line tools for development, testing, and debugging of HubProxy. Includes scripts for starting the development environment, simulating webhook events, and querying the event store. ### Tools - **`./tools/dev.sh`**: Starts the complete development environment, including a test server and the proxy. Can be run with a custom webhook secret using `HUBPROXY_WEBHOOK_SECRET=my-secret ./tools/dev.sh`. - **`go run internal/cmd/dev/simulate/main.go`**: Simulates GitHub webhook events. Requires `--secret` flag. Can simulate specific event types and add delays using `--events` and `--delay` flags. - **`go run internal/cmd/dev/query/main.go`**: Allows querying stored events from the database. ``` -------------------------------- ### Get Event Statistics API Source: https://github.com/cased/hubproxy/blob/main/README.md Retrieves statistics for event types within a specified time period. ```APIDOC ## GET /api/stats ### Description Returns event type statistics for a given time period. ### Method GET ### Endpoint /api/stats ### Query Parameters - **since** (string) - Optional - Start time in RFC3339 format (default: 24 hours ago) ### Response #### Success Response (200) - **(object)** - An object where keys are event types and values are their counts. #### Response Example ```json { "push": 50, "pull_request": 25, "issues": 10 } ``` ``` -------------------------------- ### Get Single Event Query (GraphQL API) Source: https://github.com/cased/hubproxy/blob/main/README.md GraphQL query to retrieve details of a single event by its ID. ```graphql query { event(id: "d2a1f85a-delivery-id-123") { id type payload createdAt forwardedAt repository sender } } ``` -------------------------------- ### Combine Event Filters with Pagination Source: https://context7.com/cased/hubproxy/llms.txt Demonstrates combining multiple filters (type, repository) with pagination parameters (limit, offset) for precise event retrieval. ```bash # Combine filters with pagination curl "http://localhost:8081/api/events?type=pull_request&repository=owner/repo&limit=10&offset=20" ``` -------------------------------- ### Simulate GitHub Webhook Events Source: https://context7.com/cased/hubproxy/llms.txt Simulate GitHub webhook events using the provided Go command. Options include specifying a secret, filtering event types, and introducing a delay between simulations. ```bash go run internal/cmd/dev/simulate/main.go --secret dev-secret ``` ```bash go run internal/cmd/dev/simulate/main.go --secret dev-secret --events push,pull_request --delay 2s ``` -------------------------------- ### Query Webhook Events from Database Source: https://github.com/cased/hubproxy/blob/main/README.md Use `go run internal/cmd/dev/query/main.go` to inspect and analyze stored webhook events. Supports filtering by type, repository, and showing statistics. ```bash # Show recent events go run internal/cmd/dev/query/main.go ``` ```bash # Show event statistics go run internal/cmd/dev/query/main.go --stats ``` ```bash # Filter by event type go run internal/cmd/dev/query/main.go --type push ``` ```bash # Filter by repository go run internal/cmd/dev/query/main.go --repo "owner/repo" ``` -------------------------------- ### Run HubProxy Tests and Linter Source: https://github.com/cased/hubproxy/blob/main/README.md Commands to run the test suite and linter for the HubProxy project to ensure code quality and correctness. ```bash # Run the tests (go test ./...) go test ./... # Run the linter (golangci-lint run ./...) golangci-lint run ./... ``` -------------------------------- ### Configure Tailscale Integration for HubProxy Source: https://github.com/cased/hubproxy/blob/main/README.md Enable Tailscale integration using --enable-tailscale, providing your auth key and desired hostname. This allows GitHub to send webhooks to your private network. ```bash hubproxy --enable-tailscale --ts-authkey=ts-abc123... --ts-hostname=hubproxy ``` -------------------------------- ### Test Database Connections Source: https://github.com/cased/hubproxy/blob/main/README.md Commands to test connections to PostgreSQL, MySQL, and SQLite databases. ```bash # Test PostgreSQL connection psql "postgres://user:pass@localhost:5432/hubproxy" ``` ```bash # Test MySQL connection mysql -h localhost -P 3306 -u user -p hubproxy ``` ```bash # Test SQLite database sqlite3 .cache/hubproxy.db ``` -------------------------------- ### Configure HubProxy with a Config File Source: https://github.com/cased/hubproxy/blob/main/README.md Specify the path to your configuration file using the --config flag. Ensure your webhook secret is set as an environment variable. ```bash export HUBPROXY_WEBHOOK_SECRET="your-secret-here" hubproxy --config config.yaml ``` -------------------------------- ### Get Single Webhook Event by ID Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Retrieve a specific webhook event using its unique ID. The response includes detailed information about the event. ```graphql query { event(id: "event-id") { id type payload createdAt error repository sender replayedFrom originalTime } } ``` -------------------------------- ### Watch Test Server Logs Source: https://github.com/cased/hubproxy/blob/main/README.md Use `tail -f` to monitor the `testserver.log` file in real-time to verify webhook events. ```bash # Watch events in real-time tail -f .cache/testserver.log ``` -------------------------------- ### Get Event Statistics Query (GraphQL API) Source: https://github.com/cased/hubproxy/blob/main/README.md GraphQL query to retrieve event statistics, such as counts by event type, within a specified time range. ```graphql query { stats(since: "2024-02-01T00:00:00Z") { type count } } ``` -------------------------------- ### Contribute to HubProxy: Git Workflow Source: https://github.com/cased/hubproxy/blob/main/README.md Standard Git commands for contributing to the HubProxy project, including forking, creating branches, committing changes, and opening pull requests. ```bash # Create a feature branch (git checkout -b feature/amazing-feature) git checkout -b feature/amazing-feature # Commit your changes (git commit -am 'Add amazing feature') git commit -am 'Add amazing feature' # Push to the branch (git push origin feature/amazing-feature) git push origin feature/amazing-feature ``` -------------------------------- ### List Webhook Events API Request Source: https://github.com/cased/hubproxy/blob/main/README.md HTTP GET request to list webhook events. Supports filtering by type, repository, sender, time range, forwarding status, and pagination. ```http GET /api/events ``` -------------------------------- ### Query Replayed Events Source: https://github.com/cased/hubproxy/blob/main/README.md Use the `Forwarded` filter to list all replayed events. Ensure `storage.ListEvents` is imported. ```go events, err := storage.ListEvents(QueryOptions{ Forwarded: true, }) ``` -------------------------------- ### Replay Events via GraphQL Mutations Source: https://context7.com/cased/hubproxy/llms.txt Use GraphQL mutations to replay events, offering granular control over response fields. Supports replaying single events by ID or events within a time range with filters. ```bash curl -X POST "http://localhost:8081/graphql" \ -H "Content-Type: application/json" \ -d '{ \ "query": "mutation { replayEvent(id: \"d2a1f85a-delivery-id-123\") { replayedCount events { id type forwardedAt replayedFrom originalTime } } }" \ }' ``` ```bash curl -X POST "http://localhost:8081/graphql" \ -H "Content-Type: application/json" \ -d '{ \ "query": "mutation { replayRange(since: \"2024-02-01T00:00:00Z\", until: \"2024-02-02T00:00:00Z\", type: \"push\", repository: \"owner/repo\", limit: 10) { replayedCount events { id type replayedFrom originalTime } } }" \ }' ``` -------------------------------- ### Query Stored Events Source: https://context7.com/cased/hubproxy/llms.txt Query stored events using the provided Go command. This tool is useful for inspecting the data persisted by HubProxy. ```bash go run internal/cmd/dev/query/main.go ``` -------------------------------- ### Go Storage Interface Source: https://context7.com/cased/hubproxy/llms.txt Programmatic access to HubProxy's storage layer using a Go interface, enabling custom integrations for listing, retrieving, and managing events. ```APIDOC ## Go Storage Interface ### Description Provides a Go interface for interacting with the HubProxy storage backend. Allows for programmatic operations such as listing events with various filters, retrieving a single event by ID, getting event statistics, and marking events as forwarded. ### Usage Import the necessary packages and initialize the storage implementation (e.g., `sql.New`). ### Key Methods - **ListEvents(ctx context.Context, opts QueryOptions) ([]Event, int64, error)**: Lists events with specified query options. - **QueryOptions** struct includes: - **Types** ([]string) - Filter by event types. - **Repository** (string) - Filter by repository. - **Since** (time.Time) - Filter events since this time. - **Limit** (int) - Maximum number of events to return. - **Offset** (int) - Offset for pagination. - **OnlyNonForwarded** (bool) - If true, returns only non-forwarded events. - **GetEvent(ctx context.Context, id string) (Event, error)**: Retrieves a single event by its ID. - **GetStats(ctx context.Context, since time.Time) (map[string]int64, error)**: Retrieves event statistics since a specified time. - **MarkForwarded(ctx context.Context, id string) error**: Marks an event as forwarded. - **CreateSchema(ctx context.Context) error**: Creates the necessary database schema. - **Close() error**: Closes the storage connection. ### Code Example ```go package main import ( "context" "time" "hubproxy/internal/storage" "hubproxy/internal/storage/sql" ) func main() { ctx := context.Background() // Initialize storage store, err := sql.New("sqlite:hubproxy.db") if err != nil { panic(err) } defer store.Close() // Create schema if err := store.CreateSchema(ctx); err != nil { panic(err) } // List events with filters events, total, err := store.ListEvents(ctx, storage.QueryOptions{ Types: []string{"push", "pull_request"}, Repository: "owner/repo", Since: time.Now().Add(-24 * time.Hour), Limit: 50, Offset: 0, }) // Get only non-forwarded events (pending delivery) pendingEvents, _, err := store.ListEvents(ctx, storage.QueryOptions{ OnlyNonForwarded: true, }) // Get a single event by ID event, err := store.GetEvent(ctx, "d2a1f85a-delivery-id-123") // Get event statistics stats, err := store.GetStats(ctx, time.Now().Add(-24 * time.Hour)) // Returns: map[string]int64{"push": 50, "pull_request": 25} // Mark an event as forwarded err = store.MarkForwarded(ctx, "d2a1f85a-delivery-id-123") } ``` ``` -------------------------------- ### GraphQL API Source: https://github.com/cased/hubproxy/blob/main/README.md Provides a flexible GraphQL interface for querying and manipulating webhook events. Includes an interactive GraphiQL interface. ```APIDOC ## GraphQL API ### Description HubProxy also provides a GraphQL API that mirrors the functionality of the REST API with more flexibility in querying. The GraphQL endpoint also serves an interactive GraphiQL interface when accessed from a browser, allowing you to explore and test queries. ### Endpoint /graphql ### Queries #### List Events ```graphql query { events( type: "push", repository: "owner/repo", sender: "username", since: "2024-02-01T00:00:00Z", until: "2024-02-02T00:00:00Z", limit: 10, offset: 0 ) { events { id type payload createdAt forwardedAt repository sender replayedFrom originalTime } total } } ``` #### Get Single Event ```graphql query { event(id: "d2a1f85a-delivery-id-123") { id type payload createdAt forwardedAt repository sender } } ``` #### Get Event Statistics ```graphql query { stats(since: "2024-02-01T00:00:00Z") { type count } } ``` ### Mutations #### Replay Single Event ```graphql mutation { replayEvent(id: "d2a1f85a-delivery-id-123") { replayedCount events { id type forwardedAt replayedFrom originalTime } } } ``` #### Replay Events by Time Range ```graphql mutation { replayRange( since: "2024-02-01T00:00:00Z", until: "2024-02-02T00:00:00Z", type: "push", repository: "owner/repo", sender: "username", limit: 10 ) { replayedCount events { id type forwardedAt replayedFrom originalTime } } } ``` ``` -------------------------------- ### Replay Events by Time Range (REST API) Source: https://context7.com/cased/hubproxy/llms.txt Replay webhook events within a specified time range using the REST API. Both 'since' and 'until' parameters are required. Optional filters like 'type', 'repository', and 'limit' can be applied. ```bash curl -X POST "http://localhost:8081/api/replay?since=2024-02-01T00:00:00Z&until=2024-02-02T00:00:00Z" ``` ```bash curl -X POST "http://localhost:8081/api/replay?since=2024-02-01T00:00:00Z&until=2024-02-02T00:00:00Z&type=push&repository=owner/repo" ``` ```bash curl -X POST "http://localhost:8081/api/replay?since=2024-02-01T00:00:00Z&until=2024-02-02T00:00:00Z&limit=10" ``` -------------------------------- ### Query: events Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Lists webhook events with filtering and pagination options. ```APIDOC ## Query: events ### Description Lists webhook events with filtering and pagination options. ### Method GET (or POST for complex queries) ### Endpoint /graphql ### Parameters #### Query Parameters - **type** (String) - Optional - Filter events by type. - **repository** (String) - Optional - Filter events by repository. - **sender** (String) - Optional - Filter events by sender. - **since** (DateTime) - Optional - Filter events occurring after this timestamp. - **until** (DateTime) - Optional - Filter events occurring before this timestamp. - **limit** (Int) - Optional - Maximum number of events to return. - **offset** (Int) - Optional - Number of events to skip. ### Response #### Success Response (200) - **events** (Array) - A list of webhook event objects. - **id** (String) - Unique identifier for the event. - **type** (String) - The type of the event. - **payload** (Object) - The event payload data. - **createdAt** (DateTime) - Timestamp when the event was created. - **error** (String) - Error message if the event processing failed. - **repository** (String) - The repository associated with the event. - **sender** (String) - The sender of the event. - **replayedFrom** (DateTime) - Timestamp if the event was replayed. - **originalTime** (DateTime) - Original timestamp of the event. - **total** (Int) - The total number of events matching the query. ### Request Example ```graphql query { events( type: "push" repository: "my-repo" limit: 10 ) { events { id type createdAt repository sender } total } } ``` ``` -------------------------------- ### List All Webhook Events Source: https://context7.com/cased/hubproxy/llms.txt Use this `curl` command to list all stored webhook events. The default limit is 50 events per request. ```bash # List all events (default limit: 50) curl "http://localhost:8081/api/events" ``` -------------------------------- ### Filter Query by Type and Repository Source: https://context7.com/cased/hubproxy/llms.txt Filter query results by event type and repository. Ensure the specified type and repository format are correct. ```bash go run internal/cmd/dev/query/main.go --type push --repo "owner/repo" ``` -------------------------------- ### Filter Webhook Events by Type Source: https://context7.com/cased/hubproxy/llms.txt Query webhook events filtered by their specific type, such as 'push'. ```bash # Filter by event type curl "http://localhost:8081/api/events?type=push" ``` -------------------------------- ### REST API: Replay Events by Time Range Source: https://context7.com/cased/hubproxy/llms.txt Replay webhook events within a specified time range, with optional filtering by type, repository, and a limit on the number of events. ```APIDOC ## POST /api/replay ### Description Replays webhook events within a specified time range. Supports filtering by event type, repository, and limiting the number of replayed events. ### Method POST ### Endpoint /api/replay ### Query Parameters - **since** (string) - Required - The start of the time range for events to replay (ISO 8601 format). - **until** (string) - Required - The end of the time range for events to replay (ISO 8601 format). - **type** (string) - Optional - Filters events by type (e.g., "push"). - **repository** (string) - Optional - Filters events by repository (e.g., "owner/repo"). - **limit** (integer) - Optional - The maximum number of events to replay. ### Response #### Success Response (200) - **replayed_count** (integer) - The number of events successfully replayed. - **events** (array) - An array of replayed event objects. - **id** (string) - The unique identifier for the replayed event. - **type** (string) - The type of the event. - **replayed_from** (string) - The original event identifier. - **original_time** (string) - The timestamp of the original event. ### Response Example ```json { "replayed_count": 5, "events": [ { "id": "event1-replay-uuid1", "type": "push", "replayed_from": "event1", "original_time": "2024-02-01T10:00:00Z" } ] } ``` ``` -------------------------------- ### Filter Webhook Events by Repository Source: https://context7.com/cased/hubproxy/llms.txt Retrieve webhook events associated with a specific repository, identified by 'owner/repo'. ```bash # Filter by repository curl "http://localhost:8081/api/events?repository=owner/repo" ``` -------------------------------- ### GraphQL Interface Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md The GraphQL interface for HubProxy is available at the /graphql endpoint. ```APIDOC ## GraphQL Interface The GraphQL interface for HubProxy is available at `/graphql` on the API server. Interactive tools like GraphiQL and Playground are also accessible at this endpoint when accessed from a browser. ``` -------------------------------- ### Mutation: replayRange Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Replays multiple webhook events within a specified time range and with optional filters. ```APIDOC ## Mutation: replayRange ### Description Replays multiple webhook events within a specified time range and with optional filters. ### Method POST ### Endpoint /graphql ### Parameters #### Request Body - **since** (DateTime) - Required - The start of the time range for replaying events. - **until** (DateTime) - Required - The end of the time range for replaying events. - **type** (String) - Optional - Filter events by type. - **repository** (String) - Optional - Filter events by repository. - **sender** (String) - Optional - Filter events by sender. - **limit** (Int) - Optional - Maximum number of events to replay within the range. ### Response #### Success Response (200) - **replayRange** (Object) - **replayedCount** (Int) - The number of events successfully replayed. - **events** (Array) - A list of the replayed webhook event objects. - **id** (String) - Unique identifier for the event. - **type** (String) - The type of the event. - **payload** (Object) - The event payload data. - **createdAt** (DateTime) - Timestamp when the event was created. - **repository** (String) - The repository associated with the event. - **sender** (String) - The sender of the event. - **replayedFrom** (DateTime) - Timestamp if the event was replayed. - **originalTime** (DateTime) - Original timestamp of the event. ### Request Example ```graphql mutation { replayRange( since: "2023-01-01T00:00:00Z" until: "2023-01-02T00:00:00Z" repository: "my-repo" limit: 50 ) { replayedCount events { id type createdAt repository sender } } } ``` ``` -------------------------------- ### Query: stats Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Fetches statistics for webhook events within a specified time range. ```APIDOC ## Query: stats ### Description Fetches statistics for webhook events within a specified time range. ### Method GET (or POST for complex queries) ### Endpoint /graphql ### Parameters #### Query Parameters - **since** (DateTime) - Required - The start of the time range for statistics. ### Response #### Success Response (200) - **stats** (Array) - An array of statistics objects. - **type** (String) - The type of the event. - **count** (Int) - The number of events of this type. ### Request Example ```graphql query { stats(since: "2023-01-01T00:00:00Z") { type count } } ``` ``` -------------------------------- ### Replay Events by Time Range (REST API) Source: https://github.com/cased/hubproxy/blob/main/README.md Use this endpoint to replay all webhook events within a specified time range. Requires 'since' and 'until' parameters in RFC3339 format. ```http POST /api/replay ``` -------------------------------- ### Query Original Events That Have Been Replayed Source: https://github.com/cased/hubproxy/blob/main/README.md Use the `HasReplayedEvents` filter to find original events that have been replayed. Ensure `storage.ListEvents` is imported. ```go events, err := storage.ListEvents(QueryOptions{ HasReplayedEvents: true, }) ``` -------------------------------- ### Replay Single Event by ID Source: https://github.com/cased/hubproxy/blob/main/README.md Replay a single event using its original ID. The function `storage.ReplayEvent` is used for this purpose. ```go // Replay a single event by its ID event, err := storage.ReplayEvent("d2a1f85a-delivery-id-123") ``` -------------------------------- ### SQL Schema for Event Storage Source: https://github.com/cased/hubproxy/blob/main/README.md Defines the 'events' table structure for storing webhook event details, including ID, type, payload, headers, timestamps, and replay information. Indexes are included for efficient querying. ```sql CREATE TABLE events ( id VARCHAR(255) PRIMARY KEY, -- GitHub delivery ID type VARCHAR(50) NOT NULL, -- GitHub event type payload TEXT NOT NULL, -- Event payload as JSON headers TEXT, -- HTTP headers as JSON created_at TIMESTAMP NOT NULL, -- When the event was received forwarded_at TIMESTAMP, -- When the event was forwarded error TEXT, -- Error message if delivery failed repository VARCHAR(255), -- Repository full name sender VARCHAR(255), -- GitHub username replayed_from VARCHAR(255), -- Original event ID if this is a replay original_time TIMESTAMP -- Original event time if this is a replay ); -- Indexes for efficient querying CREATE INDEX idx_created_at ON events (created_at); CREATE INDEX idx_forwarded_at ON events (forwarded_at); CREATE INDEX idx_type ON events (type); CREATE INDEX idx_repository ON events (repository); CREATE INDEX idx_sender ON events (sender); CREATE INDEX idx_replayed_from ON events (replayed_from); ``` -------------------------------- ### List Webhook Events Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Use this query to list webhook events. You can filter by type, repository, sender, and time range, and control pagination with limit and offset. ```graphql query { events( type: String repository: String sender: String since: DateTime until: DateTime limit: Int offset: Int ) { events { id type payload createdAt error repository sender replayedFrom originalTime } total } } ``` -------------------------------- ### Replay Events by Time Range Mutation (GraphQL API) Source: https://github.com/cased/hubproxy/blob/main/README.md GraphQL mutation to replay events within a specified time range, with optional filtering by type, repository, and sender. Supports pagination. ```graphql mutation { replayRange( since: "2024-02-01T00:00:00Z", until: "2024-02-02T00:00:00Z", type: "push", repository: "owner/repo", sender: "username", limit: 10 ) { replayedCount events { id type forwardedAt replayedFrom originalTime } } } ``` -------------------------------- ### Replay Multiple Webhook Events within a Time Range Source: https://github.com/cased/hubproxy/blob/main/internal/graphql/README.md Replay multiple webhook events within a specified time range. Filtering options include type, repository, sender, and a limit for the number of events to replay. ```graphql mutation { replayRange( since: "2023-01-01T00:00:00Z" until: "2023-01-02T00:00:00Z" type: String repository: String sender: String limit: Int ) { replayedCount events { id type payload createdAt repository sender replayedFrom originalTime } } } ``` -------------------------------- ### List Events Query (GraphQL API) Source: https://github.com/cased/hubproxy/blob/main/README.md GraphQL query to list events with filtering by type, repository, sender, and time range. Supports pagination with limit and offset. ```graphql query { events( type: "push", repository: "owner/repo", sender: "username", since: "2024-02-01T00:00:00Z", until: "2024-02-02T00:00:00Z", limit: 10, offset: 0 ) { events { id type payload createdAt forwardedAt repository sender replayedFrom originalTime } total } } ```