create-bulkhead

Bulkhead Pattern Generator

Creates Bulkhead pattern infrastructure for resource isolation and fault containment.

When to Use

Scenario	Example
External API calls	Limit concurrent requests to payment gateway
Database connections	Pool size limiting
CPU-intensive work	Limit by CPU cores
Multi-instance	Redis-based coordination

Component Characteristics

BulkheadInterface

• Common interface for all isolation strategies
• Acquire and release semantics
• Capacity monitoring

Strategies

• Semaphore Bulkhead: Limits concurrent executions
• Thread Pool Bulkhead: Isolates execution with dedicated pool
• Queue-based Bulkhead: Limits with waiting queue

BulkheadFullException

• Thrown when bulkhead capacity exhausted
• Contains bulkhead name and capacity info

---

Generation Process

Step 1: Generate Core Components

Path: src/Infrastructure/Resilience/Bulkhead/

1. BulkheadInterface.php — Common interface
2. BulkheadConfig.php — Configuration value object
3. BulkheadFullException.php — Exception with capacity info

Step 2: Generate Bulkhead Implementation

Choose based on use case:

1. SemaphoreBulkhead.php — Local semaphore-based limiting
2. DistributedSemaphoreBulkhead.php — Redis-based for multi-instance

Step 3: Generate Registry (Optional)

1. BulkheadRegistry.php — Manages multiple bulkheads

Step 4: Generate Tests

1. SemaphoreBulkheadTest.php — Bulkhead behavior tests
2. BulkheadConfigTest.php — Configuration tests

---

File Placement

Component	Path
All Classes	src/Infrastructure/Resilience/Bulkhead/
Unit Tests	tests/Unit/Infrastructure/Resilience/Bulkhead/

---

Naming Conventions

Component	Pattern	Example
Interface	BulkheadInterface	BulkheadInterface
Semaphore	SemaphoreBulkhead	SemaphoreBulkhead
Distributed	DistributedSemaphoreBulkhead	DistributedSemaphoreBulkhead
Config	BulkheadConfig	BulkheadConfig
Registry	BulkheadRegistry	BulkheadRegistry
Exception	BulkheadFullException	BulkheadFullException
Test	{ClassName}Test	SemaphoreBulkheadTest

---

Quick Template Reference

BulkheadInterface

interface BulkheadInterface
{
    public function execute(callable $operation): mixed;
    public function tryAcquire(): bool;
    public function release(): void;
    public function getAvailablePermits(): int;
    public function getActiveCount(): int;
    public function getName(): string;
}

BulkheadConfig

final readonly class BulkheadConfig
{
    public function __construct(
        public int $maxConcurrentCalls = 10,
        public int $maxWaitDuration = 0,
        public bool $fairness = true
    ) {}

    public static function default(): self;
    public static function forCpuBound(int $cpuCores): self;
    public static function forIoBound(int $cpuCores): self;
    public static function forExternalService(int $maxConnections): self;
}

---

Usage Example

// Create limiter
$bulkhead = new SemaphoreBulkhead(
    name: 'payment-gateway',
    config: BulkheadConfig::forExternalService(maxConnections: 20),
    logger: $logger
);

// Execute with isolation
try {
    $result = $bulkhead->execute(fn() => $client->charge($request));
} catch (BulkheadFullException $e) {
    return Result::serviceOverloaded();
}

---

Use Case Selection

Use Case	Bulkhead Type	Config
External API calls	Semaphore	Limited by API rate limits
Database connections	Semaphore	Limited by pool size
CPU-intensive work	Semaphore	Limited by CPU cores
Multi-instance	Distributed	Redis-based coordination
Mixed workloads	Registry	Per-service configuration

---

Anti-patterns to Avoid

Anti-pattern	Problem	Solution
Global Bulkhead	Single point of contention	Per-service bulkheads
No Release	Permit leak	Always release in finally
Wrong Size	Too small = rejected, too large = no protection	Right-size per service
No Metrics	Can't monitor usage	Track acquired/rejected
Infinite Wait	Thread starvation	Set maxWaitDuration
No Fallback	Hard failure on full	Provide degraded response

---

References

For complete PHP templates and examples, see:

• references/templates.md — BulkheadInterface, Config, SemaphoreBulkhead, DistributedSemaphoreBulkhead, Registry
• references/examples.md — PaymentGatewayAdapter, ConnectionPool, OrderService examples and tests