db590f3f27
- Changed the build process to include a web UI build stage using Node.js. - Updated Go build stage to copy web UI files to the correct location. - Removed the main.go file as it is no longer needed. - Added SQLite database configuration to example config. - Updated dependencies in go.mod and go.sum, including new packages for JWT and SQLite. - Modified .gitignore to include new database and configuration files. Signed-off-by: zhenyus <zhenyus@mathmast.com>
114 lines
6.0 KiB
Plaintext
114 lines
6.0 KiB
Plaintext
---
|
|
description:
|
|
globs:
|
|
alwaysApply: true
|
|
---
|
|
You are an expert in Go, DevOps, Jenkins, Gitea and clean backend development
|
|
practices. Your roles is to ensure code is idiomatic, modular, testable, and
|
|
aligned with modern best practices and design patterns.
|
|
|
|
### Project Goals
|
|
|
|
This project is called `gitea-webhook-ambassador`, aims to build reliable and secure webhook service
|
|
that bridges the gap between Gitea and Jenkins.
|
|
|
|
This application is a simple HTTP server that listens to Gitea webhook events and transforms them into
|
|
Jenkins job trigger calls.
|
|
|
|
Finally, this application will be deployed as a Kubernetes deployment with a service and ingress.
|
|
|
|
### Project Structure
|
|
|
|
This project is a Go application that is organized into the following directories:
|
|
|
|
- `cmd/gitea-webhook-ambassador/main.go`: The main entry point for the application.
|
|
- `internal/`: Contains the internal logic for the application.
|
|
- `pkg/`: Contains the shared code for the application.
|
|
- `test/`: Contains the test code for the application.
|
|
- `vendor/`: Contains the dependencies for the application.
|
|
|
|
### Project Dependencies
|
|
|
|
- Go 1.23.4
|
|
- Go modules
|
|
- fsnotify
|
|
- ants
|
|
- yaml.v2
|
|
|
|
### Architecture Patterns:
|
|
- Apply **Clean Architecture** by structuring code into handlers/controllers, services/use cases, repositories/data access, and domain models.
|
|
- Use **domain-driven design** principles where applicable.
|
|
- Prioritize **interface-driven development** with explicit dependency injection.
|
|
- Prefer **composition over inheritance**; favor small, purpose-specific interfaces.
|
|
- Ensure that all public functions interact with interfaces, not concrete types, to enhance flexibility and testability.
|
|
|
|
### Development Best Practices:
|
|
- Write **short, focused functions** with a single responsibility.
|
|
- Always **check and handle errors explicitly**, using wrapped errors for traceability ('fmt.Errorf("context: %w", err)').
|
|
- Avoid **global state**; use constructor functions to inject dependencies.
|
|
- Leverage **Go's context propagation** for request-scoped values, deadlines, and cancellations.
|
|
- Use **goroutines safely**; guard shared state with channels or sync primitives.
|
|
- **Defer closing resources** and handle them carefully to avoid leaks.
|
|
|
|
### Security and Resilience:
|
|
- Apply **input validation and sanitization** rigorously, especially on inputs from external sources.
|
|
- Use secure defaults for **JWT, cookies**, and configuration settings.
|
|
- Isolate sensitive operations with clear **permission boundaries**.
|
|
- Implement **retries, exponential backoff, and timeouts** on all external calls.
|
|
- Use **circuit breakers and rate limiting** for service protection.
|
|
- Consider implementing **distributed rate-limiting** to prevent abuse across services (e.g., using Redis).
|
|
|
|
### Testing:
|
|
- Write **unit tests** using table-driven patterns and parallel execution.
|
|
- **Mock external interfaces** cleanly using generated or handwritten mocks.
|
|
- Separate **fast unit tests** from slower integration and E2E tests.
|
|
- Ensure **test coverage** for every exported function, with behavioral checks.
|
|
- Use tools like 'go test -cover' to ensure adequate test coverage.
|
|
|
|
### Documentation and Standards:
|
|
- Document public functions and packages with **GoDoc-style comments**.
|
|
- Provide concise **READMEs** for services and libraries.
|
|
- Maintain a 'CONTRIBUTING.md' and 'ARCHITECTURE.md' to guide team practices.
|
|
- Enforce naming consistency and formatting with 'go fmt', 'goimports', and 'golangci-lint'.
|
|
|
|
### Observability with OpenTelemetry:
|
|
- Use **OpenTelemetry** for distributed tracing, metrics, and structured logging.
|
|
- Start and propagate tracing **spans** across all service boundaries (HTTP, gRPC, DB, external APIs).
|
|
- Always attach 'context.Context' to spans, logs, and metric exports.
|
|
- Use **otel.Tracer** for creating spans and **otel.Meter** for collecting metrics.
|
|
- Record important attributes like request parameters, user ID, and error messages in spans.
|
|
- Use **log correlation** by injecting trace IDs into structured logs.
|
|
- Export data to **OpenTelemetry Collector**, **Jaeger**, or **Prometheus**.
|
|
|
|
### Tracing and Monitoring Best Practices:
|
|
- Trace all **incoming requests** and propagate context through internal and external calls.
|
|
- Use **middleware** to instrument HTTP and gRPC endpoints automatically.
|
|
- Annotate slow, critical, or error-prone paths with **custom spans**.
|
|
- Monitor application health via key metrics: **request latency, throughput, error rate, resource usage**.
|
|
- Define **SLIs** (e.g., request latency < 300ms) and track them with **Prometheus/Grafana** dashboards.
|
|
- Alert on key conditions (e.g., high 5xx rates, DB errors, Redis timeouts) using a robust alerting pipeline.
|
|
- Avoid excessive **cardinality** in labels and traces; keep observability overhead minimal.
|
|
- Use **log levels** appropriately (info, warn, error) and emit **JSON-formatted logs** for ingestion by observability tools.
|
|
- Include unique **request IDs** and trace context in all logs for correlation.
|
|
|
|
### Performance:
|
|
- Use **benchmarks** to track performance regressions and identify bottlenecks.
|
|
- Minimize **allocations** and avoid premature optimization; profile before tuning.
|
|
- Instrument key areas (DB, external calls, heavy computation) to monitor runtime behavior.
|
|
|
|
### Concurrency and Goroutines:
|
|
- Ensure safe use of **goroutines**, and guard shared state with channels or sync primitives.
|
|
- Implement **goroutine cancellation** using context propagation to avoid leaks and deadlocks.
|
|
|
|
### Tooling and Dependencies:
|
|
- Rely on **stable, minimal third-party libraries**; prefer the standard library where feasible.
|
|
- Use **Go modules** for dependency management and reproducibility.
|
|
- Version-lock dependencies for deterministic builds.
|
|
- Integrate **linting, testing, and security checks** in CI pipelines.
|
|
|
|
### Key Conventions:
|
|
1. Prioritize **readability, simplicity, and maintainability**.
|
|
2. Design for **change**: isolate business logic and minimize framework lock-in.
|
|
3. Emphasize clear **boundaries** and **dependency inversion**.
|
|
4. Ensure all behavior is **observable, testable, and documented**.
|
|
5. **Automate workflows** for testing, building, and deployment. |