spiderly 19.15.0 → 19.16.1

package/agent/docs/backend-testing/index.md

@@ -1,6 +1,6 @@
 ---
 name: backend-testing
-description: Unit-test a Spiderly backend service against an EF Core InMemory database — covers the two InMemory pitfalls that silently corrupt assertions (the change tracker masking a missing SaveChanges, and WithTransactionAsync throwing TransactionIgnoredWarning). Use when writing xUnit/NUnit tests for entity services, business logic, or save/delete hooks against an InMemory DbContext, or when an InMemory-backed test passes/throws for reasons that don't match production.
+description: Unit-test a Spiderly backend service against an EF Core InMemory database — covers the two InMemory pitfalls that silently corrupt assertions (the change tracker masking a missing SaveChanges, and WithTransactionAsync throwing TransactionIgnoredWarning). Use when writing xUnit/NUnit tests for entity services, business logic, or save/delete hooks against an InMemory DbContext, or when an InMemory-backed test passes/throws for reasons that don't match production. Also covers setting the clock a test runs at (a fake `TimeProvider`), which Spiderly's audit stamps and token, API-key and outbox expiry read.
 ---
 
 # Backend Testing (EF Core InMemory)
@@ -63,3 +63,41 @@ Pass a stable `dbName` (e.g. one per test, `Guid.NewGuid().ToString()`) so each
 ## When InMemory isn't enough
 
 InMemory ignores relational constraints (unique indexes, FK cascade, check constraints, `[Required]` at the DB level), provider-specific SQL, and real transaction semantics. If the behavior under test depends on any of those, prefer the **SQLite in-memory** provider (`UseSqlite("DataSource=:memory:")`, keep the connection open) or a disposable real database — don't assert relational guarantees against `UseInMemoryDatabase`.
+
+## Controlling the clock
+
+Spiderly reads the time from the `TimeProvider` registered in the app's container. `AddSpiderly` registers `TimeProvider.System` unless the app registers its own, the same way ASP.NET Core's `AddAuthentication` does. That one clock:
+
+- stamps `CreatedAt` / `ModifiedAt` in `SaveChanges`;
+- sets and checks the expiry of access, refresh and login-verification tokens and the external-login nonce, checks an API key's `ExpiresAt`, and judges a bearer token's lifetime on each request;
+- decides when an outbox row is due for retry, which handled rows retention purges, and how old the health check says the backlog is.
+
+ASP.NET Core's own authentication handlers read the same registration. A test sets the time by registering a fake clock, e.g. `FakeTimeProvider` from the `Microsoft.Extensions.TimeProvider.Testing` package:
+
+```csharp
+using Microsoft.Extensions.Time.Testing;
+
+FakeTimeProvider clock = new(new DateTimeOffset(2030, 1, 1, 12, 0, 0, TimeSpan.Zero));
+services.AddSingleton<TimeProvider>(clock); // before or after AddSpiderly, which adds the system clock only when none is registered
+
+// ... save, issue a token, create an API key ...
+
+clock.Advance(TimeSpan.FromHours(2)); // the fake stands still until the test moves it
+```
+
+In a `WebApplicationFactory`, make that registration in `ConfigureTestServices`. Your own code that needs the current time should take `TimeProvider` in its constructor and call `GetUtcNow()`, so it reads the same clock as the stamps and expiries it compares against. Reading `DateTime.UtcNow` beside it gives the code two clocks, and a test with a fake clock can only control one of them.
+
+A context built with `new`, as in the InMemory examples above, is outside the container and stamps the system clock. Give it the test's clock through its options:
+
+```csharp
+ServiceProvider clockOnly = new ServiceCollection()
+    .AddSingleton<TimeProvider>(clock)
+    .BuildServiceProvider();
+
+MyAppDbContext context = new(new DbContextOptionsBuilder<MyAppDbContext>()
+    .UseInMemoryDatabase(dbName)
+    .UseApplicationServiceProvider(clockOnly)
+    .Options);
+```
+
+The clock does not move a cookie's `Expires`: the client judges that by its own clock, so `CookieManager` keeps setting it from the machine's. Libraries that read the machine's clock themselves, such as Hangfire's schedules, are not moved by it either.

package/agent/docs/background-jobs/index.md

@@ -0,0 +1,87 @@
+---
+name: background-jobs
+description: Write and schedule Hangfire background jobs in a Spiderly app so the container builds every job. Use when adding a job class, enqueueing a job, adding a recurring job, opting in with spiderly.AddJobs, or seeing "is not registered in the container, so it is not built".
+---
+
+# Background Jobs
+
+Spiderly runs background work on Hangfire. Opt in to the job seam and every job is a registered service: a host that
+validates its service graph at boot judges each job's constructor, and Hangfire builds jobs only from the container.
+
+## Opt in
+
+```csharp
+services.AddSpiderly<MyDbContext>(Configuration, spiderly =>
+{
+    // ...
+    spiderly.AddJobs(typeof(Startup).Assembly, typeof(InvoiceExportJob).Assembly);
+});
+```
+
+`AddJobs` registers every non-abstract class implementing `ISpiderlyJob` in the given assemblies (scoped: one instance
+per job run) and replaces Hangfire.NetCore's job activator with `SpiderlyJobActivator`. It works with
+`services.AddHangfire(...)` before or after it. A second call adds assemblies.
+
+## Write a job
+
+```csharp
+using Spiderly.Shared.Jobs;
+
+public class InvoiceExportJob : ISpiderlyJob
+{
+    private readonly IApplicationDbContext _context;
+
+    public InvoiceExportJob(IApplicationDbContext context) => _context = context;
+
+    public async Task ExportAsync(long invoiceId) { /* ... */ }
+}
+```
+
+- Implement `ISpiderlyJob`, take dependencies in the constructor, keep method arguments simple and serializable.
+- No `services.AddScoped<InvoiceExportJob>()` needed: the scan registers it. A registration of your own (another
+  lifetime, a factory) wins over the scan's.
+
+## Schedule it
+
+Use the typed methods, which accept only an `ISpiderlyJob`:
+
+```csharp
+// Injected IBackgroundJobClient
+backgroundJobClient.EnqueueJob<InvoiceExportJob>(job => job.ExportAsync(invoiceId));
+
+// IRecurringJobManager, in the Configure phase
+IRecurringJobManager jobs = app.ApplicationServices.GetRequiredService<IRecurringJobManager>();
+jobs.AddOrUpdateJob<InvoiceExportJob>("invoice-export-nightly", job => job.ExportAllAsync(), "0 2 * * *",
+    new RecurringJobOptions { TimeZone = TimeZoneInfo.Utc });
+```
+
+Do not schedule with Hangfire's `Enqueue<T>` / `AddOrUpdate<T>`: they accept any type, so an unmarked job compiles,
+and the activator refuses it when it runs. An app can ban them with a banned-symbols analyzer to make that a compile
+error.
+
+## What fails where
+
+| Mistake | Where it fails |
+| --- | --- |
+| Job class without `ISpiderlyJob` scheduled through the typed methods | Compile error |
+| Job scheduled through Hangfire's own API, never registered | When it runs: `The Hangfire job '...' is not registered in the container, so it is not built.` |
+| Job's constructor needs a service nobody registered | At boot when the host validates its graph (`ValidateOnBuild`), else when it runs |
+
+## Spiderly's own jobs
+
+`AddOutbox<TOutbox>()` registers the dispatcher, retention and health jobs that `app.SpiderlyUseOutboxRecurringJob<TOutbox>()`
+schedules; `AddNotifications(...)` registers `NotificationDeliveryJob`. They are registered whether or not you call
+`AddJobs`. `SpiderlyUseOutboxRecurringJob` schedules through the container's `IRecurringJobManager`, so it needs
+`services.AddHangfire(...)`.
+
+## Generic jobs
+
+A marked open generic class (`ImportJob<TSource> : ISpiderlyJob`) is registered as an open generic. The container
+cannot validate an open generic registration at boot, so also register each closed form you schedule
+(`services.AddScoped<ImportJob<CsvSource>>()`) to have it judged there.
+
+## Testing
+
+A job is a plain class: construct it with its dependencies and call its method. To test what code schedules, pass a fake
+`IBackgroundJobClient` / `IRecurringJobManager` that records the `Job` it is handed (`job.Type`, `job.Method`,
+`job.Args`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spiderly",
-  "version": "19.15.0",
+  "version": "19.16.1",
   "author": "Filip Trivan",
   "license": "MIT",
   "description": "Spiderly Angular Library to use in combination with Spiderly.",