fixes and docs

Author: arrilot

README.md

@@ -4,24 +4,110 @@
 [![Tests](https://github.com/ensi-platform/laravel-initiator-propagation/actions/workflows/run-tests.yml/badge.svg?branch=master)](https://github.com/ensi-platform/laravel-initiator-propagation/actions/workflows/run-tests.yml)
 [![Total Downloads](https://img.shields.io/packagist/dt/ensi/laravel-initiator-propagation.svg?style=flat-square)](https://packagist.org/packages/ensi/laravel-initiator-propagation)
 
-Generates Laravel application code from Open Api Specification files
+Provides a bunch of ready-to use middleware to integrate [ensi/initiator-propagation](https://github.com/ensi-platform/php-initiator-propagation/) in Laravel application.
+You are free to replace any of them with your own implementations.
 
 ## Installation
 
 You can install the package via composer:
 
 `composer require ensi/laravel-initiator-propagation`
 
-You can publish config file like this:
+Publish config file like this:
 
 `php artisan vendor:publish --provider="Ensi\LaravelInitiatorPropagation\LaravelInitiatorPropagationServiceProvider"`
 
 ## Basic Usage
 
-## Setting initiator
+```php
+$holder = resolve(InitiatorHolder::class);
+var_dump($holder->getInitiator());
+$holder->setInitiator(new InitiatorDTO(...));
+```
 
-You can use build-in `Ensi\InitiatorPropagation\ParseInitiatorHeaderLaravelMiddleware` to populate `InitiatorHolder` with data from incoming request.
-It's also recommended to add `$this->app->instance(InitiatorHolder::class, InitiatorHolder::getInstance());` to one of your service providers to make `InitiatorHolder` singleton injectable via Laravel Service Container
+### HTTP Requests
+
+#### Setting initiator
+
+You typically create a new initiator when you receive a HTTP request coming from a client you do not own. E.g in an API Gateway.
+There is a built-in `Ensi\LaravelInitiatorPropagation\SetInitiatorHttpMiddleware` for that.
+It creates an `InitiatorDTO` and places it to the `InitiatorHolder` singleton.
+- `userId` and `entrypoint` are set from request.
+- `app` is set according to config options.
+- `userType` is set from the package config. `userType` is empty for a not authenticated user.
+- `correlationId` and `startedAt` are set from request headers according to config options or generated from scratch.
+- `realUserId` and `realUserType` are left empty strings.
+
+Be sure to add the midlleware AFTER Laravel middleware that sets authenticated user. 
+In practice it likely means that you have to place the middleare at the very bottom of `middlewareGroups` in `app/Http/Kernel`
+
+#### Parsing incoming initiator
+
+Add `Ensi\LaravelInitiatorPropagation\ParseInitiatorHeaderMiddleware` to `app/Http/Kernel` middleware property.
+This middleware parses `X-Initiator` HTTP header, deserializes it into `InitiatorDTO` object and places it to the `InitiatorHolder` singleton.
+
+#### Propagating initiator to outcomming HTTP request
+The package provides a `Ensi\InitiatorPropagation\PropagateInitiatorGuzzleMiddleware` Guzzle Middleware that converts ` resolve(InitiatorHolder::class)->getInitiator()` back to `X-Inititator` header and sets this header for all outcomming guzzle request.
+
+You can add it to your guzzle stack like this:
+
+```php
+$handlerStack = new HandlerStack(Utils::chooseHandler());
+$handlerStack->push(new PropagateInitiatorGuzzleMiddleware());
+```
+
+### CLI
+
+#### Artisan Commands
+
+There is a custom artisan `Ensi\LaravelInitiatorPropagation\SetInitiatorArtisanMiddleware` that sets new initiator in every artisan command that you run.
+You can add it to the `app\Console\Kernel` like that:
+
+```php
+public function bootstrap()
+{
+    parent::bootstrap();
+    (new SetInitiatorArtisanMiddleware())->handle();
+}
+```
+This middleware sets artisan command name (including argument, excluding options) as `$initiatorDTO->entrypoint`.
+If your custom artisan command makes guzzle HTTP requests to other apps the `PropagateInitiatorGuzzleMiddleware` uses this initiator.
+This middleware also works fine for [Laravel Task Scheduling](https://laravel.com/docs/latest/scheduling).
+
+#### Queue Jobs
+
+You typically want to persist initiator between incoming HTTP request and queued job.
+The package can help you here aswell. Unfortunately you need to touch a given job:
+
+```php
+use Ensi\LaravelInitiatorPropagation\Job;
+
+// Extend the job from package
+class TestJob extends Job implements ShouldQueue 
+{
+    public function __construct(protected Customer $customer)
+    {
+        // Do not forget to call parent constuctor
+        parent::__construct();
+    }
+
+    public function handle()
+    {
+        // Initiator is automatically persisted to InitiatorHolder via job middleware in parent class, 
+        // You do not need to persist it manually
+    }
+}
+```
+
+#### Laravel Queable Actions
+
+If you use [spatie/laravel-queueable-action](https://github.com/spatie/laravel-queueable-action) package to dispatch actions instead of jobs you do not need to mess with every job separately.
+
+Just publish `laravel-queueable-action` config and set the special Job class there:
+
+```php 
+'job_class' => \Ensi\InitiatorPropagation\ActionJob::class,
+```
 
 ## Contributing
 

config/initiator-propagation.php

@@ -2,5 +2,25 @@
 
 return [
     'app_code' => '',
-    'default_user_type' => '',
+    'set_initiator_http_middleware' => [
+        'default_user_type' => '',
+
+        /**
+         * Middleware parses this header to get `appCode`.
+         * If the header is not specified here or in a request, `appCode` is taken from `app_code` config value
+         */ 
+        'app_code_header' => '',
+
+        /**
+         * Middleware parses this header to get `correlationId`
+         * If the header is not specified here or in a request, `correlationId` is generated from scratch.
+         */
+        'corelation_id_header' => '',
+
+        /**
+         * Middleware parses this header to get `startedAt`
+         * If the header is not specified here or in a request, `startedAt` is generated from scratch.
+         */
+        'started_at_header' => '',
+    ]
 ];

src/SetInitiatorArtisanMiddleware.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Ensi\LaravelInitiatorPropagation;
+
+
+use Ensi\InitiatorPropagation\InitiatorDTO;
+use Ensi\InitiatorPropagation\InitiatorHolder;
+use Illuminate\Container\Container;
+
+class SetInitiatorArtisanMiddleware
+{
+    public function handle(): void
+    {
+        Container::getInstance()->make(InitiatorHolder::class)->setInitiator(InitiatorDTO::fromScratch(
+            app: config('initiator-propagation.app_code'),
+            entrypoint: $this->extractEntrypointFromInput(),
+        ));
+    }
+
+    protected function extractEntrypointFromInput(): string
+    {
+        $argv = $_SERVER['argv'] ?? [];
+        $argvWithoutOptions = array_filter($argv, fn ($arg) => !str_starts_with($arg, '-'));
+
+        return implode(" ", $argvWithoutOptions);
+    }
+}

src/SetInitiatorHttpMiddleware.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace Ensi\LaravelInitiatorPropagation;
+
+use Closure;
+use Ensi\InitiatorPropagation\InitiatorDTO;
+use Ensi\InitiatorPropagation\InitiatorHolder;
+use Illuminate\Container\Container;
+use Illuminate\Http\Request;
+
+class SetInitiatorHttpMiddleware
+{
+    public function handle(Request $request, Closure $next): mixed
+    {
+        $user = $request->user();
+        $config = config('initiator-propagation', []);
+        $mc = config('initiator-propagation.set_initiator_http_middleware', []);
+
+        $initiator = InitiatorDTO::fromScratch(
+            userId: $user ? $user->getId() : "",
+            userType: $user ? config('initiator-propagation.set_initiator_http_middleware.default_user_type', '') : "",
+            app: !empty($mc['app_code_header']) ? $request->header($mc['app_code_header']) : ($config['app_code'] ?? ''),
+            entrypoint: $this->extractEntrypoint($request),
+            correlationId: !empty($mc['correlation_id_header']) ? $request->header($mc['correlation_id_header']) : '',
+            startedAt: !empty($mc['started_at_header']) ? $request->header($mc['started_at_header']) : ''
+        );
+
+        Container::getInstance()->make(InitiatorHolder::class)->setInitiator($initiator);
+
+        return $next($request);
+    }
+
+    protected function extractEntrypoint(Request $request): string
+    {
+        if ($request->route()?->uri) {
+            return "/" . ltrim($request->route()?->uri, "/");
+        }
+
+        return $request->getRequestUri();
+    }
+}