316 lines
8.1 KiB
Markdown
316 lines
8.1 KiB
Markdown
# Pipeline Package Gap Analysis
|
|
|
|
## Overview
|
|
|
|
This document analyzes the gaps between our Pipeline package's actual implementation and our documentation, identifying areas that need implementation or documentation updates.
|
|
|
|
> **Related Documentation**
|
|
> - See [Pipeline Package Specification](pipeline_package_specification.md) for current implementation
|
|
> - See [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md) for overall status
|
|
> - See [Foundation Integration Guide](foundation_integration_guide.md) for integration patterns
|
|
> - See [Testing Guide](testing_guide.md) for testing approaches
|
|
> - See [Getting Started Guide](getting_started.md) for development setup
|
|
|
|
## Implementation Gaps
|
|
|
|
### 1. Missing Laravel Features
|
|
```dart
|
|
// Documented but not implemented:
|
|
|
|
// 1. Pipeline Hub
|
|
class PipelineHub {
|
|
// Need to implement:
|
|
Pipeline pipeline(String name);
|
|
void defaults(List<Pipe> pipes);
|
|
Pipeline middleware();
|
|
Pipeline bus();
|
|
}
|
|
|
|
// 2. Pipeline Conditions
|
|
class Pipeline {
|
|
// Need to implement:
|
|
Pipeline when(bool Function() callback);
|
|
Pipeline unless(bool Function() callback);
|
|
Pipeline whenCallback(Function callback);
|
|
}
|
|
|
|
// 3. Pipeline Caching
|
|
class Pipeline {
|
|
// Need to implement:
|
|
void enableCache();
|
|
void clearCache();
|
|
dynamic getCached(String key);
|
|
}
|
|
```
|
|
|
|
### 2. Existing Features Not Documented
|
|
|
|
```dart
|
|
// Implemented but not documented:
|
|
|
|
// 1. Type Registration
|
|
class Pipeline {
|
|
/// Registers pipe types for string resolution
|
|
void registerPipeType(String name, Type type);
|
|
|
|
/// Type map for string resolution
|
|
final Map<String, Type> _typeMap = {};
|
|
}
|
|
|
|
// 2. Method Invocation
|
|
class Pipeline {
|
|
/// Invokes methods on pipe instances
|
|
Future<dynamic> invokeMethod(
|
|
dynamic instance,
|
|
String methodName,
|
|
List<dynamic> arguments
|
|
);
|
|
|
|
/// Sets method to call on pipes
|
|
Pipeline via(String method);
|
|
}
|
|
|
|
// 3. Exception Handling
|
|
class Pipeline {
|
|
/// Logger for pipeline
|
|
final Logger _logger;
|
|
|
|
/// Handles exceptions in pipeline
|
|
dynamic handleException(dynamic passable, Object e);
|
|
}
|
|
```
|
|
|
|
### 3. Integration Points Not Documented
|
|
|
|
```dart
|
|
// 1. Container Integration
|
|
class Pipeline {
|
|
/// Container reference
|
|
final Container? _container;
|
|
|
|
/// Gets container instance
|
|
Container getContainer();
|
|
|
|
/// Sets container instance
|
|
Pipeline setContainer(Container container);
|
|
}
|
|
|
|
// 2. Reflection Integration
|
|
class Pipeline {
|
|
/// Resolves pipe types using mirrors
|
|
Type? _resolvePipeType(String pipeClass) {
|
|
try {
|
|
for (var lib in currentMirrorSystem().libraries.values) {
|
|
// Reflection logic...
|
|
}
|
|
} catch (_) {}
|
|
}
|
|
}
|
|
|
|
// 3. Logging Integration
|
|
class Pipeline {
|
|
/// Logger instance
|
|
final Logger _logger;
|
|
|
|
/// Logs pipeline events
|
|
void _logPipelineEvent(String message, [Object? error]);
|
|
}
|
|
```
|
|
|
|
## Documentation Gaps
|
|
|
|
### 1. Missing API Documentation
|
|
|
|
```dart
|
|
// Need to document:
|
|
|
|
/// Registers a pipe type for string resolution.
|
|
///
|
|
/// This allows pipes to be specified by string names in the through() method.
|
|
///
|
|
/// Example:
|
|
/// ```dart
|
|
/// pipeline.registerPipeType('auth', AuthMiddleware);
|
|
/// pipeline.through(['auth']);
|
|
/// ```
|
|
void registerPipeType(String name, Type type);
|
|
|
|
/// Sets the method to be called on pipe instances.
|
|
///
|
|
/// By default, the 'handle' method is called. This method allows
|
|
/// customizing which method is called on each pipe.
|
|
///
|
|
/// Example:
|
|
/// ```dart
|
|
/// pipeline.via('process').through([MyPipe]);
|
|
/// // Will call process() instead of handle()
|
|
/// ```
|
|
Pipeline via(String method);
|
|
```
|
|
|
|
### 2. Missing Integration Examples
|
|
|
|
```dart
|
|
// Need examples for:
|
|
|
|
// 1. Container Integration
|
|
var pipeline = Pipeline(container)
|
|
..through([
|
|
AuthMiddleware,
|
|
container.make<LoggingMiddleware>(),
|
|
'validation' // Resolved from container
|
|
]);
|
|
|
|
// 2. Exception Handling
|
|
pipeline.through([
|
|
(passable, next) async {
|
|
try {
|
|
return await next(passable);
|
|
} catch (e) {
|
|
logger.error('Pipeline error', e);
|
|
throw PipelineException(e.toString());
|
|
}
|
|
}
|
|
]);
|
|
|
|
// 3. Method Customization
|
|
pipeline.via('process')
|
|
.through([
|
|
ProcessingPipe(), // Will call process() instead of handle()
|
|
ValidationPipe()
|
|
]);
|
|
```
|
|
|
|
### 3. Missing Test Coverage
|
|
|
|
```dart
|
|
// Need tests for:
|
|
|
|
void main() {
|
|
group('Type Registration', () {
|
|
test('resolves string pipes to types', () {
|
|
var pipeline = Pipeline(container);
|
|
pipeline.registerPipeType('auth', AuthMiddleware);
|
|
|
|
await pipeline
|
|
.through(['auth'])
|
|
.send(request)
|
|
.then(handler);
|
|
|
|
verify(() => container.make<AuthMiddleware>()).called(1);
|
|
});
|
|
});
|
|
|
|
group('Method Invocation', () {
|
|
test('calls custom methods on pipes', () {
|
|
var pipeline = Pipeline(container);
|
|
var pipe = MockPipe();
|
|
|
|
await pipeline
|
|
.via('process')
|
|
.through([pipe])
|
|
.send(data)
|
|
.then(handler);
|
|
|
|
verify(() => pipe.process(any, any)).called(1);
|
|
});
|
|
});
|
|
}
|
|
```
|
|
|
|
## Implementation Priority
|
|
|
|
1. **High Priority**
|
|
- Pipeline hub (Laravel compatibility)
|
|
- Pipeline conditions (Laravel compatibility)
|
|
- Better exception handling
|
|
|
|
2. **Medium Priority**
|
|
- Pipeline caching
|
|
- Better type resolution
|
|
- Performance optimizations
|
|
|
|
3. **Low Priority**
|
|
- Additional helper methods
|
|
- Extended testing utilities
|
|
- Debug/profiling tools
|
|
|
|
## Next Steps
|
|
|
|
1. **Implementation Tasks**
|
|
- Add pipeline hub
|
|
- Add pipeline conditions
|
|
- Add caching support
|
|
- Improve exception handling
|
|
|
|
2. **Documentation Tasks**
|
|
- Document type registration
|
|
- Document method invocation
|
|
- Document exception handling
|
|
- Add integration examples
|
|
|
|
3. **Testing Tasks**
|
|
- Add type registration tests
|
|
- Add method invocation tests
|
|
- Add exception handling tests
|
|
- Add integration tests
|
|
|
|
Would you like me to:
|
|
1. Start implementing missing features?
|
|
2. Update documentation for existing features?
|
|
3. Create test cases for missing coverage?
|
|
|
|
## Development Guidelines
|
|
|
|
### 1. Getting Started
|
|
Before implementing pipeline features:
|
|
1. Review [Getting Started Guide](getting_started.md)
|
|
2. Check [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md)
|
|
3. Follow [Testing Guide](testing_guide.md)
|
|
4. Use [Foundation Integration Guide](foundation_integration_guide.md)
|
|
5. Review [Pipeline Package Specification](pipeline_package_specification.md)
|
|
|
|
### 2. Implementation Process
|
|
For each pipeline feature:
|
|
1. Write tests following [Testing Guide](testing_guide.md)
|
|
2. Implement following Laravel patterns
|
|
3. Document following [Getting Started Guide](getting_started.md#documentation)
|
|
4. Integrate following [Foundation Integration Guide](foundation_integration_guide.md)
|
|
|
|
### 3. Quality Requirements
|
|
All implementations must:
|
|
1. Pass all tests (see [Testing Guide](testing_guide.md))
|
|
2. Meet Laravel compatibility requirements
|
|
3. Follow integration patterns (see [Foundation Integration Guide](foundation_integration_guide.md))
|
|
4. Match specifications in [Pipeline Package Specification](pipeline_package_specification.md)
|
|
|
|
### 4. Integration Considerations
|
|
When implementing pipeline features:
|
|
1. Follow patterns in [Foundation Integration Guide](foundation_integration_guide.md)
|
|
2. Ensure Laravel compatibility per [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md)
|
|
3. Use testing approaches from [Testing Guide](testing_guide.md)
|
|
4. Follow development setup in [Getting Started Guide](getting_started.md)
|
|
|
|
### 5. Performance Guidelines
|
|
Pipeline system must:
|
|
1. Handle nested pipelines efficiently
|
|
2. Minimize memory usage in long pipelines
|
|
3. Support async operations
|
|
4. Scale with number of stages
|
|
5. Meet performance targets in [Laravel Compatibility Roadmap](laravel_compatibility_roadmap.md#performance-benchmarks)
|
|
|
|
### 6. Testing Requirements
|
|
Pipeline tests must:
|
|
1. Cover all pipeline types
|
|
2. Test stage ordering
|
|
3. Verify error handling
|
|
4. Check conditional execution
|
|
5. Follow patterns in [Testing Guide](testing_guide.md)
|
|
|
|
### 7. Documentation Requirements
|
|
Pipeline documentation must:
|
|
1. Explain pipeline patterns
|
|
2. Show integration examples
|
|
3. Cover error handling
|
|
4. Include performance tips
|
|
5. Follow standards in [Getting Started Guide](getting_started.md#documentation)
|