README

Project Overview

Alize is a Laravel package that provides the core building blocks to integrate with Mexico's number portability platform (NUMLEX/ABD). It includes:

A SOAP HTTP endpoint to receive inbound NPC messages.
A SOAP client for outbound messages with XSD validation and circuit breaker safeguards.
SFTP-based daily files reconciliation.
Orchestrators, jobs, and domain services for end-to-end portability flows.

Primary audience: internal dev teams and external integrators embedding this package into a host Laravel application.

Project Type & Tech Summary

Type: Laravel package (library)
PHP: ^8.1 (tested with PHP 8.4 during development)
Laravel: 10.x | 11.x | 12.x (via illuminate/support)
Database: Uses the host application's default database connection (migrations included)
Cache: Uses the host application's cache store (circuit breaker state)
Queue: Uses the host application's queue driver
External services:
- NUMLEX SOAP endpoint (inbound and outbound)
- NUMLEX SFTP daily files

Quick Start (High-Level)

Install: composer require ometra/hela-alize
Publish config: php artisan vendor:publish --tag=alize-config
Run migrations: php artisan migrate
Configure environment: NUMLEX credentials, SOAP endpoint, optional TLS certs, SFTP settings (see Deployment Instructions)
Ensure scheduler and a queue worker are running
Verify: php artisan alize:check-connection and hit the SOAP route to test inbound

Observability

Built-in logging works without host setup and writes to storage/logs/alize.log by default.
The package does not expose observability HTTP endpoints by itself.
Host applications should integrate ObservabilityService and define /health, /metrics, and optional diagnostics routes explicitly.
Alerting thresholds:
- ALIZE_OBSERVABILITY_POISON_WARN_THRESHOLD
- ALIZE_OBSERVABILITY_POISON_FAIL_THRESHOLD
- ALIZE_OBSERVABILITY_REPLAY_BACKLOG_WARN_THRESHOLD
- ALIZE_OBSERVABILITY_REPLAY_BACKLOG_FAIL_THRESHOLD
- ALIZE_OBSERVABILITY_REPLAY_BACKLOG_STALE_MINUTES
- ALIZE_OBSERVABILITY_PROCESSING_LATENCY_P95_WARN_MS
- ALIZE_OBSERVABILITY_PROCESSING_LATENCY_P95_FAIL_MS
- ALIZE_OBSERVABILITY_PROCESSING_LATENCY_SAMPLE_SIZE
- ALIZE_OBSERVABILITY_PROCESSING_FLOW_P95_WARN_MS
- ALIZE_OBSERVABILITY_PROCESSING_FLOW_P95_FAIL_MS
- ALIZE_OBSERVABILITY_PROCESSING_FLOW_MIN_SAMPLES
- ALIZE_OBSERVABILITY_PROCESSING_FLOW_TOP_N
- ALIZE_OBSERVABILITY_PROCESSING_REGRESSION_ENABLED
- ALIZE_OBSERVABILITY_PROCESSING_REGRESSION_WARN_DELTA_MS
- ALIZE_OBSERVABILITY_PROCESSING_REGRESSION_FAIL_DELTA_MS
- ALIZE_OBSERVABILITY_PROCESSING_REGRESSION_RELEASE_TAG
Diagnostics controls for host integrations:
- ALIZE_OBSERVABILITY_DIAGNOSTICS_LIMIT
- ALIZE_OBSERVABILITY_DIAGNOSTICS_MAX_LIMIT
Scheduled alerting controls:
- ALIZE_OBSERVABILITY_ALERTING_ENABLED
- ALIZE_OBSERVABILITY_ALERTING_SCHEDULE
- ALIZE_OBSERVABILITY_ALERTING_DIAGNOSTICS_LIMIT
- ALIZE_OBSERVABILITY_ALERTING_LOG_HEALTHY

Health now includes operational checks for poison-message accumulation, replay backlog aging, and inbound processing latency. Metrics now expose gauges for poison age, replay backlog size/age, inbound retry pressure, and processing latency p95/max/avg.

Inbound processing metrics also expose a breakdown by handler, message type, and outcome so degraded p95 can be attributed to a specific flow. The Prometheus families are alize_inbound_processing_breakdown_total, alize_inbound_processing_breakdown_p95_ms, and alize_inbound_processing_breakdown_avg_ms.

Actionable hotspot metrics are also emitted for top flows and recent trend delta: alize_inbound_processing_hotspot_alert_state, alize_inbound_processing_hotspot_p95_ms, alize_inbound_processing_hotspot_samples, and alize_inbound_processing_hotspot_delta_p95_ms.

Flow regression metrics (current vs persisted baseline per release tag) are emitted as alize_inbound_processing_regression_alert_state, alize_inbound_processing_regression_delta_p95_ms, alize_inbound_processing_regression_baseline_p95_ms, and alize_inbound_processing_regression_current_p95_ms.

The diagnostics endpoint also supports handler, type_code, outcome, only_regressions, sort, and direction query parameters for targeted flow analysis.

Baseline lifecycle commands:

php artisan alize:observability-baselines show --release-tag=release-2026.03
php artisan alize:observability-baselines freeze --release-tag=release-2026.03
php artisan alize:observability-baselines reset --release-tag=release-2026.03 --force

Operational alerting command:

php artisan alize:observability-alerts --limit=3
php artisan alize:observability-alerts --limit=3 --fail-on-alert

Host app custom routes example:

use Illuminate\Support\Facades\Route;
use Ometra\HelaAlize\Services\ObservabilityService;

Route::get('/health', function (ObservabilityService $observability) {
    $payload = $observability->health();
    $status = ($payload['status'] ?? 'healthy') === 'unhealthy' ? 503 : 200;

    return response()->json($payload, $status);
});

Route::get('/metrics', function (ObservabilityService $observability) {
    return response($observability->metrics(), 200, [
        'Content-Type' => 'text/plain; version=0.0.4; charset=utf-8',
    ]);
});

Security: IP Whitelist Middleware

The package provides RestrictByIpAddress middleware to protect sensitive observability endpoints:

// Route configuration with IP whitelist
Route::prefix('api/v1/observability')
    ->middleware(Ometra\HelaAlize\Http\Middleware\RestrictByIpAddress::class)
    ->group(function () {
        Route::get('/health', [HealthController::class, 'show']);
        Route::get('/metrics', [MetricsController::class, 'index']);
        Route::get('/diagnostics/flows', [DiagnosticsFlowsController::class, 'show']);
    });

Configuration (.env):

# Comma-separated list of allowed IPs (multiple formats supported)
ALIZE_SECURITY_IP_WHITELIST=192.168.1.100,10.0.0.0/8,172.16.1.*,2001:db8::1

# Leave empty to allow all IPs (default, backward compatible)
ALIZE_SECURITY_IP_WHITELIST=

Supported IP formats:

Exact: 192.168.1.100, 2001:db8::1
CIDR: 192.168.0.0/16, 2001:db8::/32
Wildcard: 192.168.1.*, 10.*.*.*

See OBSERVABILITY_INTEGRATION.md for detailed examples.

Inbound message orchestration runs on a queued listener with retries/backoff.
Default queue behavior:
- queue name: alize-inbound
- tries: 5
- timeout: 120s
- backoff: 10s, 30s, 120s
Optional environment overrides:
- ALIZE_INBOUND_QUEUE_CONNECTION
- ALIZE_INBOUND_QUEUE_NAME
- ALIZE_INBOUND_QUEUE_TRIES
- ALIZE_INBOUND_QUEUE_TIMEOUT_SECONDS
- ALIZE_INBOUND_QUEUE_BACKOFF_1
- ALIZE_INBOUND_QUEUE_BACKOFF_2
- ALIZE_INBOUND_QUEUE_BACKOFF_3
- ALIZE_INBOUND_LOCK_ENABLED
- ALIZE_INBOUND_LOCK_SECONDS
- ALIZE_INBOUND_LOCK_KEY_PREFIX
Terminal failures (after exhausting retries) are persisted as poison-message metadata in parsed_data._processing_failure and ack_status=ERROR.

Ensure a queue worker is running to process inbound events asynchronously.

Documentation Index

Standards

This documentation follows the project's Coding Standards and PHPDoc Style Guide.

ometra / hela-alize

Maintainers

Package info

Statistics

Security