Waterline Laravel Package

Getting Started

Waterline is an operator console for a Laravel Durable Workflow runtime. It is not a workflow authoring tool or a business dashboard; use it to answer operational questions: Which workflows are stuck? Which queues are backing up? What failed? Can I safely retry or repair this instance?

Minimal setup:

1. Install it alongside your existing Durable Workflow package and run the workflow migrations first.
2. Require and publish the package:

composer require laravel-workflow/waterline
php artisan vendor:publish --tag=waterline-config
php artisan vendor:publish --tag=waterline-assets
php artisan migrate

3. Open config/waterline.php and review the route path, middleware, authorization gate, queue connection, and retention/display options.
4. Confirm the route is registered:

php artisan route:list | grep -i waterline

5. Protect the UI before using it anywhere non-local. At minimum put it behind auth and an operator gate:

Gate::define('viewWaterline', fn (User $user) => $user->isOperator());

Then bind that gate through the package’s middleware/authorization config.

Where to look first:

• The package README and config/waterline.php.
• The registered routes and middleware.
• Your Durable Workflow runtime tables and queue configuration.
• The package’s service provider for extension points, gates, and route bindings.

First practical use case: deploy Waterline to staging, trigger a known failing workflow, then use the UI to inspect its history, identify the failed step, inspect the queue/retry state, and retry or repair it. That gives the team a safe rehearsal before using it in production incident response.

Implementation Patterns

Incident triage workflow. Wire alerts and logs to Waterline by including the workflow ID in error messages. During an incident, the on-call engineer opens the workflow instance, reads the history, checks the failing activity and retry count, then inspects queue depth and worker health before retrying. Avoid blind retries until the failure cause is understood.

Queue health monitoring. Use Waterline as the first screen when workflows appear delayed. Compare queue backlog, oldest job age, failed jobs, and retry volume against worker count. This is often faster than querying job tables manually during a deploy or traffic spike.

Retry and repair playbooks. Treat retry/repair actions as operational runbooks, not ad-hoc buttons. Document which failures are safe to retry, which require repairing state first, and who is allowed to do it. For example: payment timeout → verify provider state → repair workflow payload/state → retry activity, rather than retrying immediately.

Support and engineering deep links. Add links from your application’s order/user/admin screens to the relevant Waterline workflow view using the workflow ID:

// Discover the actual named route with: php artisan route:list
$url = route('waterline.workflows.show', $workflowId);

This reduces support round-trips: support can open the workflow history and confirm whether the process is running, failed, retrying, or complete.

Read-only vs operator access. If the package supports middleware or gate-based access, define at least two roles: viewers who can inspect history and queues, and operators who can retry/repair. In many teams, support gets read-only access while only on-call engineers get repair permissions.

Deploy correlation. Record deploy markers, release versions, or timestamps in logs. When failures spike after a deployment, use Waterline history to compare workflow start/failure times with deploy windows. This is especially useful for activities that depend on changed code, schemas, or external APIs.

Multi-tenant and environment separation. Use separate Waterline instances or strict gates per environment. Do not let staging operators reach production repair actions. If your workflows carry tenant IDs, tags, or searchable metadata, standardize those fields so operators can filter quickly. If the UI does not support tenant scoping, restrict access per environment and rely on application-side links.

Pair with logs, metrics, and traces. Waterline is an operator UI, not a complete observability stack. Keep structured logs for workflow IDs, activity names, attempt numbers, and exception classes. Use Waterline to inspect state, then jump to logs/traces for stack traces and dependency latency.

Testing integration. Add feature tests for authorization and route access rather than testing the UI internals:

test('non-operators cannot access waterline', function () {
    $this->actingAs(User::factory()->create())
        ->get('/waterline')
        ->assertForbidden();
});

Also test that your app-generated deep links point to the correct workflow ID and environment.

Gotchas and Tips

• Protect it aggressively. Waterline exposes workflow history, payloads, queue state, and repair actions. Put it behind authentication, an operator gate, and preferably an IP allowlist or VPN in production. Never leave it publicly reachable.
• History may contain sensitive data. Workflow arguments, activity results, exception messages, and payloads can include PII, tokens, or internal identifiers. Review what your workflows persist and consider redaction or restricted access before enabling broad visibility.
• Repair is dangerous. Retrying or repairing can duplicate side effects if activities are not idempotent. Require idempotency keys or external-state checks before retrying payment, email, provisioning, or other side-effecting activities.
• Do not use Waterline as your only alerting system. It is a UI for investigation. Pair it with metrics/alerts on queue age, failure rate, workflow duration, and stuck instances. Link alerts directly to the relevant Waterline view.
• Check route and config caching. After changing the route path, middleware, or gate, run php artisan config:clear and php artisan route:clear in environments where caching is enabled.
• Confirm the UI is reading the same runtime store. If you use multiple databases, read replicas, or per-node SQLite, Waterline may show stale or incomplete state. Ensure it points at the authoritative workflow database and queue backend.
• Watch read-replica lag. In production, a lagging replica can make healthy workflows look stuck or make completed workflows appear running. Use the primary database for operational views if freshness matters.
• Long histories get expensive. Large workflow histories and payloads can make pages slow. Paginate, avoid opening huge instances unnecessarily, and set retention/pruning policies for workflow history where appropriate.
• Queue configuration matters. If Waterline displays queue health, make sure its queue connection matches the workers actually processing workflows. A mismatch produces misleading backlog numbers.
• Version pinning is prudent. The package is relatively young and has limited dependent adoption. Pin versions in composer.json, read the changelog before upgrades, and smoke-test Waterline in staging after Laravel or Durable Workflow upgrades.
• Plan for auditability. Repair and retry actions should be attributable. Log who performed them, when, which workflow/activity was affected, and the before/after state. If the package does not provide an audit trail, capture it in your own middleware or operational logs.
• Prefer named routes over hard-coded URLs. Route prefixes and middleware are configurable; use route:list and named routes so path changes do not break deep links.
• Check proxy and asset setup. Behind a load balancer or reverse proxy, ensure trusted proxies, asset URLs, and CSP rules are configured so the UI loads correctly.
• Treat it as an operator tool, not a product surface. Do not expose Waterline to end customers. Keep it in an internal admin area with clear access boundaries and environment-specific configuration.