Skip to content

Commit 6ff88d6

Browse files
intel352intel352
authored
Merge branch 'main' into copilot/fix-21
2 parents 03bc589 + 3290069 commit 6ff88d6

3 files changed

Lines changed: 271 additions & 2 deletions

File tree

‎.github/copilot-instructions.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
This is the Modular Go framework - a structured way to create modular applications in Go with module lifecycle management, dependency injection, configuration management, and multi-tenancy support. Please follow these guidelines when contributing:
2+
3+
## Code Standards
4+
5+
### Go Development
6+
- **Formatting**: All Go code must be formatted with `gofmt`. Run `go fmt ./...` before committing
7+
- **Linting**: Use `golangci-lint run` to check code quality (see `.golangci.yml` for configuration)
8+
- **Testing**:
9+
- Core framework tests: `go test ./... -v`
10+
- Module tests: Run tests for each module individually:
11+
```bash
12+
for module in modules/*/; do
13+
if [ -f "$module/go.mod" ]; then
14+
echo "Testing $module"
15+
cd "$module" && go test ./... -v && cd -
16+
fi
17+
done
18+
```
19+
- Example tests: Run tests for each example individually:
20+
```bash
21+
for example in examples/*/; do
22+
if [ -f "$example/go.mod" ]; then
23+
echo "Testing $example"
24+
cd "$example" && go test ./... -v && cd -
25+
fi
26+
done
27+
```
28+
- CLI tests: `cd cmd/modcli && go test ./... -v`
29+
- **Module Development**: Follow the established module interface patterns and provide comprehensive configuration options
30+
31+
### Required Before Each Commit
32+
- Format Go code with `gofmt`
33+
- Run `golangci-lint run` and fix any linting issues
34+
- Ensure all tests pass (core, modules, examples, and CLI):
35+
- Core: `go test ./... -v`
36+
- Modules: `for module in modules/*/; do [ -f "$module/go.mod" ] && (cd "$module" && go test ./... -v); done`
37+
- Examples: `for example in examples/*/; do [ -f "$example/go.mod" ] && (cd "$example" && go test ./... -v); done`
38+
- CLI: `cd cmd/modcli && go test ./... -v`
39+
- Update documentation when adding new features or changing APIs
40+
- Update module README files when modifying modules
41+
42+
## Development Workflow
43+
44+
### Local Development Setup
45+
1. Clone the repository: `git clone https://github.com/GoCodeAlone/modular.git`
46+
2. Install Go 1.23.0 or later (toolchain uses 1.24.2)
47+
3. Install golangci-lint: `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`
48+
4. Run tests to verify setup: `go test ./... -v`
49+
50+
### Working with Modules
51+
- Each module is in `modules/<module-name>/` with its own `go.mod`
52+
- Modules should implement the core `Module` interface
53+
- Modules can optionally implement `Startable`, `Stoppable`, `TenantAwareModule`, etc.
54+
- All modules should have comprehensive README documentation with examples
55+
56+
### Working with Examples
57+
- Examples are in `examples/<example-name>/` with their own `go.mod`
58+
- Examples demonstrate real-world usage patterns
59+
- Each example should be runnable with clear instructions
60+
- Examples help validate that the framework works as intended
61+
62+
## Repository Structure
63+
64+
### Core Framework (`/`)
65+
- **Root**: Core framework code including `application.go`, `module.go`, service registry, and configuration system
66+
- **`feeders/`**: Configuration feeders for various sources (env, yaml, json, toml)
67+
- **`cmd/modcli/`**: Command-line tool for generating modules and configurations
68+
69+
### Modules (`/modules`)
70+
Available pre-built modules:
71+
- **`auth/`**: Authentication and authorization with JWT, sessions, password hashing, OAuth2/OIDC
72+
- **`cache/`**: Multi-backend caching with Redis and in-memory support
73+
- **`chimux/`**: Chi router integration with middleware support
74+
- **`database/`**: Database connectivity and SQL operations with multiple drivers
75+
- **`eventbus/`**: Asynchronous event handling and pub/sub messaging
76+
- **`httpclient/`**: Configurable HTTP client with connection pooling and timeouts
77+
- **`httpserver/`**: HTTP/HTTPS server with TLS support and graceful shutdown
78+
- **`jsonschema/`**: JSON Schema validation services
79+
- **`letsencrypt/`**: SSL/TLS certificate automation with Let's Encrypt
80+
- **`reverseproxy/`**: Reverse proxy with load balancing and circuit breaker
81+
- **`scheduler/`**: Job scheduling with cron expressions and worker pools
82+
83+
### Examples (`/examples`)
84+
Working example applications:
85+
- **`basic-app/`**: Simple modular application with HTTP server and routing
86+
- **`reverse-proxy/`**: HTTP reverse proxy server with load balancing
87+
- **`http-client/`**: HTTP client with proxy backend integration
88+
- **`advanced-logging/`**: Advanced HTTP client logging and debugging
89+
- **`instance-aware-db/`**: Database configuration with instance awareness
90+
- **`multi-tenant-app/`**: Multi-tenant application example
91+
92+
## Key Guidelines
93+
94+
### Core Framework Development
95+
1. **Module Interface Compliance**: Ensure all modules properly implement required interfaces
96+
2. **Dependency Resolution**: Support both named and interface-based service matching
97+
3. **Configuration System**: Support validation, defaults, required fields, and multiple formats
98+
4. **Multi-tenancy**: Maintain tenant isolation and proper context handling
99+
5. **Error Handling**: Use wrapped errors with clear messages and proper error types
100+
6. **Backwards Compatibility**: Maintain API compatibility when possible
101+
102+
### Module Development
103+
1. **Interface Implementation**: Implement core `Module` interface and relevant optional interfaces
104+
2. **Configuration**: Provide comprehensive configuration with validation and defaults
105+
3. **Service Provision**: Register services that other modules can depend on
106+
4. **Documentation**: Include complete README with usage examples and configuration reference
107+
5. **Testing**: Write comprehensive unit tests and integration tests where applicable
108+
6. **Dependencies**: Minimize external dependencies and document any that are required
109+
110+
### Example Development
111+
1. **Standalone Applications**: Each example should be a complete, runnable application
112+
2. **Clear Documentation**: Include README with setup instructions and usage examples
113+
3. **Real-world Patterns**: Demonstrate practical usage patterns and best practices
114+
4. **Configuration**: Show different configuration approaches and validation
115+
5. **Error Handling**: Demonstrate proper error handling and logging
116+
117+
### CLI Tool Development
118+
1. **Code Generation**: Generate boilerplate code following established patterns
119+
2. **Interactive Prompts**: Provide user-friendly interactive configuration
120+
3. **Template System**: Use templates that reflect current best practices
121+
4. **Validation**: Validate generated code and provide helpful error messages
122+
123+
### Configuration Best Practices
124+
1. **Struct Tags**: Use `yaml`, `json`, `default`, `required`, and `desc` tags appropriately
125+
2. **Validation**: Implement `ConfigValidator` interface for custom validation logic
126+
3. **Documentation**: Use `desc` tags to document configuration options
127+
4. **Defaults**: Provide sensible defaults for optional configuration
128+
5. **Multiple Formats**: Support YAML, JSON, and TOML configuration formats
129+
130+
### Testing Strategy
131+
1. **Unit Tests**: Test individual functions and methods in isolation
132+
2. **Integration Tests**: Test module interactions and service dependencies
133+
3. **Example Tests**: Ensure examples build and run correctly
134+
4. **Mock Application**: Use the provided mock application for testing modules
135+
5. **Interface Testing**: Verify modules implement interfaces correctly
136+
137+
### Multi-tenancy Guidelines
138+
1. **Context Propagation**: Always propagate tenant context through the call chain
139+
2. **Configuration Isolation**: Ensure tenant configurations are properly isolated
140+
3. **Resource Management**: Handle tenant-specific resource creation and cleanup
141+
4. **Service Isolation**: Maintain separation between tenant-specific services
142+
143+
### Error Handling Standards
144+
1. **Error Wrapping**: Use `fmt.Errorf` with `%w` verb to wrap errors
145+
2. **Error Types**: Define specific error types for different failure modes
146+
3. **Context**: Include relevant context in error messages
147+
4. **Logging**: Log errors at appropriate levels with structured logging
148+
5. **Graceful Degradation**: Handle optional dependencies gracefully
149+
150+
## Development Tools
151+
152+
### CLI Tool (`modcli`)
153+
- Generate new modules: `modcli generate module --name MyModule`
154+
- Generate configurations: `modcli generate config --name MyConfig`
155+
- Install with: `go install github.com/GoCodeAlone/modular/cmd/modcli@latest`
156+
157+
### Debugging Tools
158+
- Debug module interfaces: `modular.DebugModuleInterfaces(app, "module-name")`
159+
- Debug all modules: `modular.DebugAllModuleInterfaces(app)`
160+
- Verbose logging for troubleshooting service dependencies and configuration
161+
162+
### Configuration Tools
163+
- Generate sample configs: `modular.SaveSampleConfig(cfg, "yaml", "config-sample.yaml")`
164+
- Support for YAML, JSON, and TOML formats
165+
- Automatic validation and default value application

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
name: "Copilot Setup Steps"
2+
3+
# Automatically run the setup steps when they are changed to allow for easy validation, and
4+
# allow manual testing through the repository's "Actions" tab
5+
on:
6+
workflow_dispatch:
7+
push:
8+
paths:
9+
- .github/workflows/copilot-setup-steps.yml
10+
pull_request:
11+
paths:
12+
- .github/workflows/copilot-setup-steps.yml
13+
14+
jobs:
15+
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
16+
copilot-setup-steps:
17+
runs-on: ubuntu-latest
18+
19+
# Set the permissions to the lowest permissions possible needed for your steps.
20+
# Copilot will be given its own token for its operations.
21+
permissions:
22+
# If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
23+
contents: read
24+
25+
# You can define any steps you want, and they will run before the agent starts.
26+
# If you do not check out your code, Copilot will do this for you.
27+
steps:
28+
- name: Checkout code
29+
uses: actions/checkout@v4
30+
31+
# Setup Go environment for modular framework development and testing
32+
- name: Setup Go
33+
uses: actions/setup-go@v5
34+
with:
35+
go-version: '^1.24.2'
36+
cache-dependency-path: go.sum
37+
38+
# Install Go dependencies and development tools
39+
- name: Install Go dependencies and tools
40+
run: |
41+
go mod download
42+
go mod verify
43+
44+
# Install golangci-lint for Go code linting
45+
- name: Install golangci-lint
46+
uses: golangci/golangci-lint-action@v7
47+
with:
48+
version: latest
49+
args: --version
50+
51+
# Install module dependencies for all modules
52+
- name: Install module dependencies
53+
run: |
54+
echo "Installing dependencies for all modules..."
55+
for module_dir in modules/*/; do
56+
if [ -f "$module_dir/go.mod" ]; then
57+
echo "Installing dependencies for $module_dir"
58+
cd "$module_dir"
59+
go mod download
60+
go mod verify
61+
cd - > /dev/null
62+
fi
63+
done
64+
65+
# Install example dependencies
66+
- name: Install example dependencies
67+
run: |
68+
echo "Installing dependencies for all examples..."
69+
for example_dir in examples/*/; do
70+
if [ -f "$example_dir/go.mod" ]; then
71+
echo "Installing dependencies for $example_dir"
72+
cd "$example_dir"
73+
go mod download
74+
go mod verify
75+
cd - > /dev/null
76+
fi
77+
done
78+
79+
# Install CLI tool dependencies
80+
- name: Install CLI tool dependencies
81+
run: |
82+
echo "Installing CLI tool dependencies..."
83+
cd cmd/modcli
84+
go mod download
85+
go mod verify
86+
cd - > /dev/null
87+
88+
# Build CLI tool for testing
89+
- name: Build CLI tool
90+
run: |
91+
cd cmd/modcli
92+
go build -o modcli .
93+
./modcli --help
94+
cd - > /dev/null
95+
96+
# Verify all tools are properly installed
97+
- name: Verify tool installations
98+
run: |
99+
echo "=== Tool Versions ==="
100+
go version
101+
golangci-lint --version
102+
echo "=== Go Environment ==="
103+
go env GOVERSION
104+
go env GOROOT
105+
go env GOPATH
106+
echo "All tools installed successfully!"

‎examples/instance-aware-db/go.mod‎

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,6 @@ module instance-aware-db
22

33
go 1.24.2
44

5-
toolchain go1.24.4
6-
75
replace github.com/GoCodeAlone/modular => ../..
86

97
replace github.com/GoCodeAlone/modular/modules/database => ../../modules/database

0 commit comments

Comments
 (0)