This document outlines the plan to extract common framework components from registry-credentials-service into the registry-credentials-service-core library to improve clone self-sufficiency and reduce code duplication across all registry-credentials-service-generated services.
- Location:
/home/mturansk/projects/src/github.com/openshift-online/registry-credentials-service-core✅ EXISTS - State: Partial skeleton implementation with missing concrete functions
- Current Issues:
- ❌ registry-credentials-service cannot compile - 19 files import broken core components
- ❌ Circular dependency - Core requires registry-credentials-service, registry-credentials-service requires Core
- ❌ Missing implementations -
buildReference(),SessionFactory.New()broken - ❌ Clone script broken - Path expansion bug, missing scripts directory
# Current registry-credentials-service build fails with:
pkg/api/presenters/project.go:10:15: undefined: buildReference
pkg/dao/project.go:26:29: d.sessionFactory.New undefined
# + 15 more critical errors across 19 filesURGENT: Both clone generation AND registry-credentials-service-core extraction are currently broken. The partial extraction has left registry-credentials-service in a non-functional state.
Current Critical Issues:
- ❌ registry-credentials-service template cannot compile (
make binaryfails) - ❌ Clone script has path expansion bugs (creates
/scripts/clone/~/projects/) - ❌ Missing framework components in incomplete core extraction
- ❌ Circular dependency prevents resolution
- ❌ Integration test failures due to broken dependencies
pkg/db/db_context/ # Transaction context management
pkg/db/transactions.go # Core transaction functions
pkg/db/transaction_middleware.go # HTTP transaction middleware
pkg/db/session.go # Database session management
pkg/db/context.go # Database context utilities
pkg/db/advisory_locks.go # Database locking mechanisms
Justification: Every clone needs transaction management, context handling, and database operations.
Key Components:
newTransaction()function for transaction creation- Transaction context management via
db_contextpackage - HTTP middleware for automatic transaction handling
- Advisory locking for concurrency control
pkg/errors/errors.go # Service error definitions and utilities
Justification: Standardized error codes and HTTP response mapping essential for all services.
Key Components:
- Service error type definitions
- HTTP status code mappings
- OpenAPI error formatting
- Common error constructors (NotFound, Validation, etc.)
pkg/auth/context.go # JWT payload extraction and context management
pkg/auth/helpers.go # Authentication utilities
Justification: Every service needs user context and auth payload handling.
Key Components:
- JWT token parsing and validation
- User context management
- Auth payload extraction utilities
- Username and account ID context helpers
pkg/logger/logger.go # OCM logger implementation
pkg/logger/operationid_middleware.go # Operation ID middleware
Justification: Structured logging with operation ID and context is universal need.
Key Components:
- OCMLogger interface and implementation
- Context-aware logging with transaction IDs
- Sentry integration for error reporting
- Operation ID middleware for request tracing
pkg/util/utils.go # Generic pointer utilities and context helpers
Justification: ToPtr, FromPtr, context helpers used across all generated entities.
Key Components:
- Generic pointer utilities (
ToPtr,FromPtr) - Empty value helpers
- String/nil conversion utilities
- Context extraction helpers
pkg/api/presenters/object_reference.go # Common reference presentation
pkg/api/presenters/time.go # Time formatting utilities
pkg/api/presenters/error.go # Error response formatting
Justification: All entities need consistent API response formatting.
Key Components:
- ObjectReference presentation utilities
- Consistent time formatting for APIs
- Error response formatting
- Common presentation patterns
test/factories/factory.go # Base factory with ID generation
Justification: Test factory base structure with KSUID generation needed by all entities.
Key Components:
- Base
Factoriesstruct for test data generation - KSUID-based ID generation (
NewID()method) - Common factory patterns and utilities
pkg/api/presenters/kind.go # Entity kind mapping
pkg/api/presenters/path.go # Entity path mapping
Justification: These are entity-specific and should remain in generator templates.
Priority: CRITICAL - Fix broken state before extraction
Actions:
-
Fix registry-credentials-service Compilation:
# Restore missing functions temporarily - Add buildReference() implementation to presenters - Fix SessionFactory.New() interface mismatch - Resolve circular dependency (remove core dependency from registry-credentials-service temporarily)
-
Fix Clone Script:
# Fix path expansion and directory inclusion - scripts/clone/main.go:67 - Add proper path expansion - Fix scripts directory exclusion - Clean up corrupted clone attempts -
Stabilization Test:
export GOROOT=/home/mturansk/go/go1.24.4.linux-amd64/go export GOPATH=/home/mturansk/go go build ./cmd/registry-credentials-service # Must succeed go run ./scripts/clone/main.go --name test-service --destination ~/test # Must work cd ~/test && make binary # Must compile
Success Criteria:
- ✅ registry-credentials-service compiles:
make binarysucceeds - ✅ Clone script works: Creates functional project
- ✅ Cloned project compiles independently
- ✅ No circular dependencies
Timeline: After stabilization complete
Actions:
-
Remove Circular Dependency:
# Fix registry-credentials-service-core/go.mod - remove registry-credentials-service dependency - Remove: require github.com/openshift-online/registry-credentials-service v0.0.1 - Make core truly independent -
Extract Infrastructure Components:
# Move ONLY infrastructure, keep business logic pkg/errors/ → registry-credentials-service-core/errors/ ✅ No dependencies pkg/db/ → registry-credentials-service-core/db/ ✅ Generic patterns pkg/controllers/generic* → registry-credentials-service-core/controllers/ ✅ Framework only pkg/services/generic* → registry-credentials-service-core/services/ ✅ CRUD patterns pkg/dao/generic* → registry-credentials-service-core/dao/ ✅ Base patterns
-
Preserve Business Logic:
# KEEP in registry-credentials-service - business-specific implementations pkg/api/dinosaur_types.go ✅ registry-credentials-service business entity pkg/services/dinosaurs.go ✅ Business logic pkg/handlers/dinosaur.go ✅ API handlers pkg/dao/dinosaur.go ✅ Business queries pkg/api/presenters/ ✅ API transformations
Success Criteria:
- registry-credentials-service builds with core library dependencies
- Core library has no registry-credentials-service dependencies
- 35+ infrastructure files moved to core
- 25+ business files remain in registry-credentials-service
Timeline: Sprint 2
Actions:
- Create
registry-credentials-service-core/auth/package - Move auth context management to core library
- Create
registry-credentials-service-core/logger/package - Move logger implementation and middleware to core
- Update middleware dependencies in registry-credentials-service
- Update clone generation templates
Success Criteria:
- Authentication and logging work via core library
- Middleware integration functions correctly
- Clone generation includes auth and logging dependencies
Timeline: Sprint 3
Actions:
- Create
registry-credentials-service-core/util/package - Move utilities to core library
- Create
registry-credentials-service-core/presenters/package - Move common presenters to core library
- Update generator templates to use core presenters
- Update clone generation process
Success Criteria:
- Utilities and presenters work via core library
- Generator templates use core library components
- Clone generation produces fully self-sufficient clones
Timeline: Sprint 4
Actions:
- Generate fresh clone to validate complete self-sufficiency
- Run comprehensive integration tests
- Update documentation and README files
- Create migration guide for existing clones
- Version and release core library
Success Criteria:
- Fresh clones work without manual intervention
- All tests pass (unit and integration)
- Documentation updated and comprehensive
- Core library properly versioned
# Prerequisites
export GOROOT=/home/mturansk/go/go1.24.4.linux-amd64/go
export GOPATH=/home/mturansk/go
cd /home/mturansk/projects/src/github.com/openshift-online/registry-credentials-service
# Test Steps
go mod tidy # ✅ Must complete without errors
go build ./cmd/registry-credentials-service # ✅ Must produce binary
make binary # ✅ Must succeed
make test # ✅ Must pass all tests
make test-integration # ✅ Must pass integration tests
# Expected Results
- registry-credentials-service binary created successfully
- All unit tests pass (0 failures)
- All integration tests pass
- No compilation errors
- No missing function errors# Test Steps
rm -rf ~/test-extraction-validation # Clean up
go run ./scripts/clone/main.go \
--name test-extraction-validation \
--destination ~/test-extraction-validation # ✅ Must complete without errors
# Path Validation
ls ~/test-extraction-validation # ✅ Directory must exist
ls ~/test-extraction-validation/scripts/ # ✅ Scripts directory must be included
test -f ~/test-extraction-validation/go.mod # ✅ go.mod must exist
# Expected Results
- Clone directory created at specified location (not ~/projects/test)
- All necessary files copied (including scripts directory)
- No path expansion errors
- No permission denied errors# Test Steps
cd ~/test-extraction-validation
go mod tidy # ✅ Must resolve dependencies
go build ./cmd/test-extraction-validation # ✅ Must compile independently
make binary # ✅ Must succeed
make test # ✅ Must pass
# Dependency Validation
go list -m all | grep registry-credentials-service-core # ✅ Should show core dependency
go build -v ./... # ✅ No missing imports
# Expected Results
- Cloned project compiles independently
- All tests pass in cloned project
- No missing dependencies
- No circular dependency errors# Test Steps
cd /home/mturansk/projects/src/github.com/openshift-online/registry-credentials-service-core
# Circular Dependency Check
grep -r "github.com/openshift-online/registry-credentials-service[^-]" . # ❌ Must return empty
go mod tidy # ✅ Must succeed
go build ./... # ✅ Must compile
go test ./... # ✅ Must pass
# Expected Results
- No imports of main registry-credentials-service project
- Core library compiles independently
- All core tests pass
- No circular dependencies# Test Steps
cd /home/mturansk/projects/src/github.com/openshift-online/registry-credentials-service
# Core Integration Check
grep -r "registry-credentials-service-core" pkg/ | wc -l # ✅ Should show expected imports
go mod tidy # ✅ Must succeed
go build ./cmd/registry-credentials-service # ✅ Must compile
make test # ✅ Must pass
# Expected Results
- registry-credentials-service successfully imports core library
- All registry-credentials-service functionality preserved
- No functionality regressions
- Tests pass with core library integration# Test Steps - Validate Infrastructure Moved
test ! -d pkg/errors/ # ✅ Should be moved to core
test ! -f pkg/db/transactions.go # ✅ Should be moved to core
test -f pkg/api/dinosaur_types.go # ✅ Business logic should remain
# Test Steps - Validate Core Contains Infrastructure
test -d ../registry-credentials-service-core/errors/ # ✅ Should exist in core
test -f ../registry-credentials-service-core/db/transactions.go # ✅ Should exist in core
# File Count Validation
find pkg/ -name "*.go" | wc -l # ✅ Should be ~25 files (business logic)
find ../registry-credentials-service-core/ -name "*.go" | wc -l # ✅ Should be ~35+ files (infrastructure)
# Expected Results
- Infrastructure files moved to core
- Business logic files remain in registry-credentials-service
- Proper separation achieved
- File counts match expectations# Test Steps
cd /home/mturansk/projects/src/github.com/openshift-online/registry-credentials-service
# Generate Fresh Clone
rm -rf ~/e2e-test-service
go run ./scripts/clone/main.go \
--name e2e-test-service \
--destination ~/e2e-test-service
# Test Clone Functionality
cd ~/e2e-test-service
go mod tidy
make binary # ✅ Must compile
make db/setup # ✅ Must setup database
make test # ✅ Must pass tests
# Test Entity Generation in Clone
go run ./scripts/generate/main.go --kind Product # ✅ Must generate entity
make generate # ✅ Must update OpenAPI
make test # ✅ Must pass with new entity
# Expected Results
- Complete clone workflow succeeds
- Generated entities work correctly
- No manual intervention required
- Database operations work
- All tests pass# Test Steps
time go build ./cmd/registry-credentials-service # ✅ Baseline: Record build time
time make test # ✅ Baseline: Record test time
# After extraction
time go build ./cmd/registry-credentials-service # ✅ Should be similar or faster
time make test # ✅ Should be similar
# Binary Size Check
ls -la registry-credentials-service # ✅ Record binary size
# After extraction - should be smaller due to reduced duplication
# Expected Results
- Build time similar or improved
- Test time similar
- Binary size reduced
- No performance regressions# If any existing clones exist, test they still work
# Test Steps for each existing clone:
cd /path/to/existing/clone
go mod tidy
go build ./... # ✅ Must still compile
make test # ✅ Must still pass
# Expected Results
- Existing clones unaffected by extraction
- No breaking changes introduced
- Backward compatibility maintained# Create comprehensive test script
cat > test-extraction.sh << 'EOF'
#!/bin/bash
set -e
# Phase 0 Tests
echo "=== Phase 0: Stabilization Tests ==="
./test-registry-credentials-service-compilation.sh
./test-clone-script.sh
./test-cloned-independence.sh
# Phase 1 Tests
echo "=== Phase 1: Extraction Tests ==="
./test-core-independence.sh
./test-core-integration.sh
./test-file-movement.sh
# Integration Tests
echo "=== Integration Tests ==="
./test-e2e-clone.sh
./test-performance.sh
./test-regression.sh
echo "✅ All extraction tests passed!"
EOF
chmod +x test-extraction.sh
./test-extraction.sh # ✅ Must pass all tests
# Expected Results
- Automated test suite passes
- Ready for CI integration
- Reliable validation process- File Count: registry-credentials-service: ~25 files, Core: ~35+ files
- Build Time: No regression (within 10%)
- Test Time: No regression (within 10%)
- Binary Size: 10-30% reduction expected
- Clone Time: No regression (within 10%)
- Zero Manual Steps: Clone → Build → Test → Run (no intervention)
- Clean Separation: Infrastructure vs Business Logic
- No Circular Dependencies: Core independent of registry-credentials-service
- Backward Compatibility: Existing clones unaffected
- ❌ Any test fails
- ❌ Performance regression >10%
- ❌ Manual intervention required
- ❌ Circular dependencies detected
- ❌ Business logic mixed with infrastructure
✅ True Self-Sufficiency: Clones work without manual framework copying
✅ Zero External Dependencies: No references to parent registry-credentials-service framework
✅ Immediate Productivity: Developers can build/test without framework knowledge
✅ Consistent Experience: All clones have complete, working framework components
✅ Consistent Framework: All clones get same tested framework version
✅ Centralized Maintenance: Bug fixes benefit all services automatically
✅ Reduced Clone Size: Less code duplication across clones
✅ Version Management: Framework can be versioned independently
✅ Quality Assurance: Core library can have dedicated testing and validation
This extraction would completely solve the framework self-sufficiency issue identified by the ocmai clone:
- ✅ Missing
newTransactionfunction → Available viaregistry-credentials-service-core/db - ✅ Transaction middleware → Available via
registry-credentials-service-core/db - ✅ Test factory base structure → Available via
registry-credentials-service-core/test - ✅ Import path corrections → Automatic via core library imports
- Create migration script to update imports
- Update go.mod to include registry-credentials-service-core dependency
- Remove duplicated framework files
- Test and validate functionality
- Provide step-by-step migration guide
- Clone maintainers update at their own pace
- Support both old and new patterns during transition
- Apply extraction only to new clones
- Existing clones remain unchanged
- Gradual adoption as clones are updated
Recommendation: Option 1 - Automatic migration ensures consistency and immediate benefits.
- Risk: Core library changes break existing clones
- Mitigation: Semantic versioning, comprehensive testing, gradual rollout
- Risk: Circular dependencies or import conflicts
- Mitigation: Careful package structure design, dependency analysis
- Risk: Additional dependency overhead
- Mitigation: Minimal core library footprint, performance testing
- Risk: Core library becomes maintenance burden
- Mitigation: Dedicated ownership, automated testing, clear contribution guidelines
- Clone generation time (should remain similar)
- Clone build time (should improve due to reduced code)
- Test execution time (should remain similar)
- Binary size (should decrease due to shared dependencies)
- Time to first successful build (should decrease significantly)
- Number of manual intervention steps (should reach zero)
- Developer onboarding time (should decrease)
- Issue reports related to framework setup (should decrease)
- Framework consistency across clones (should reach 100%)
- Test coverage in core library (should exceed 90%)
- Bug reports related to framework components (should centralize)
Priority: CRITICAL EMERGENCY - Both registry-credentials-service template and cloning are currently broken and non-functional.
-
⚠️ URGENT: Phase 0 Stabilization (This Week)- Fix registry-credentials-service compilation errors (19 broken files)
- Fix clone script path expansion bug
- Restore basic functionality
-
📋 Strategic: Phase 1 Extraction (Next Week)
- Resolve circular dependency in registry-credentials-service-core
- Extract infrastructure components properly
- Maintain business logic separation
registry-credentials-service Template State: ❌ BROKEN - Cannot compile
- Missing
buildReference()function SessionFactory.New()interface mismatch- Circular dependency with registry-credentials-service-core
Clone Script State: ❌ BROKEN - Path expansion fails
- Creates directories in wrong locations
- Missing scripts directory in clones
- Permission denied errors
registry-credentials-service-core State: ❌ INCOMPLETE - Skeleton only
- Missing concrete implementations
- Circular dependency with registry-credentials-service
- Cannot be used independently
Phase 0 Complete: registry-credentials-service compiles, clone script works, no circular dependencies Phase 1 Complete: Clean separation, infrastructure in core, business logic in registry-credentials-service Final State: Self-sufficient clones with reliable core library dependency
HIGH RISK: Current broken state blocks all registry-credentials-service usage and development
MEDIUM RISK: Extraction complexity could introduce new issues
LOW RISK: Well-tested extraction with comprehensive test plan
Next Action: IMMEDIATELY begin Phase 0 stabilization to restore basic registry-credentials-service functionality.