@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/standards/backend/integrations/hangfire/hangfire-jobs.md

@@ -0,0 +1,350 @@
+# Hangfire Background Jobs Standard
+
+> **Scope:** universal
+> **Layer:** 2 (on keyword)
+> **Keywords:** hangfire, background job, recurring, fire-and-forget, scheduled
+> **Load When:** hangfire or background job keywords detected
+
+Background job processing for .NET applications with Hangfire.
+
+---
+
+## Overview
+
+Hangfire provides:
+- Fire-and-forget jobs
+- Delayed jobs
+- Recurring jobs (cron schedules)
+- Job continuations
+- Built-in dashboard
+- Retry logic with exponential backoff
+
+**Stack:** .NET 10
+
+---
+
+## Core Principles
+
+1. **Stateless Jobs**: Job methods should be stateless and idempotent
+2. **Minimal Dependencies**: Jobs should not depend on HTTP context or scoped services
+3. **Explicit Retries**: Configure retry behavior per job type
+4. **Monitor Dashboard**: Use Hangfire Dashboard for job monitoring
+
+---
+
+## Installation & Setup
+
+### Install Packages
+
+```bash
+dotnet add package Hangfire.Core
+dotnet add package Hangfire.SqlServer
+dotnet add package Hangfire.AspNetCore
+```
+
+### Program.cs Configuration
+
+```csharp
+// Program.cs
+using Hangfire;
+using Hangfire.SqlServer;
+
+var builder = WebApplication.CreateBuilder(args);
+
+// Add Hangfire services
+builder.Services.AddHangfire(configuration => configuration
+    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
+    .UseSimpleAssemblyNameTypeSerializer()
+    .UseRecommendedSerializerSettings()
+    .UseSqlServerStorage(
+        builder.Configuration.GetConnectionString("HangfireConnection"),
+        new SqlServerStorageOptions
+        {
+            CommandBatchMaxTimeout = TimeSpan.FromMinutes(5),
+            SlidingInvisibilityTimeout = TimeSpan.FromMinutes(5),
+            QueuePollInterval = TimeSpan.Zero,
+            UseRecommendedIsolationLevel = true,
+            DisableGlobalLocks = true
+        }));
+
+builder.Services.AddHangfireServer();
+
+var app = builder.Build();
+
+// Hangfire Dashboard (protect in production!)
+app.UseHangfireDashboard("/hangfire", new DashboardOptions
+{
+    Authorization = new[] { new HangfireAuthorizationFilter() }
+});
+
+app.Run();
+```
+
+---
+
+## Job Types
+
+### Fire-and-Forget Jobs
+
+```csharp
+// Enqueue immediately
+BackgroundJob.Enqueue<IEmailService>(x => x.SendWelcomeEmail(userId));
+
+// Alternative: Static method
+BackgroundJob.Enqueue(() => Console.WriteLine("Hello, world!"));
+```
+
+### Delayed Jobs
+
+```csharp
+// Run after 1 hour
+BackgroundJob.Schedule<IReportService>(
+    x => x.GenerateMonthlyReport(),
+    TimeSpan.FromHours(1));
+
+// Run at specific time
+BackgroundJob.Schedule<INotificationService>(
+    x => x.SendReminder(userId),
+    DateTimeOffset.UtcNow.AddDays(7));
+```
+
+### Recurring Jobs
+
+```csharp
+// Run daily at 2 AM UTC
+RecurringJob.AddOrUpdate<ICleanupService>(
+    "cleanup-old-data",
+    x => x.CleanupOldRecords(),
+    Cron.Daily(2));
+
+// Run every 15 minutes
+RecurringJob.AddOrUpdate<ISyncService>(
+    "sync-external-data",
+    x => x.SyncData(),
+    "*/15 * * * *");
+```
+
+### Job Continuations
+
+```csharp
+var parentJobId = BackgroundJob.Enqueue<IOrderService>(
+    x => x.ProcessOrder(orderId));
+
+BackgroundJob.ContinueJobWith<IEmailService>(
+    parentJobId,
+    x => x.SendOrderConfirmation(orderId));
+```
+
+---
+
+## Job Service Pattern
+
+```csharp
+// Services/Jobs/IEmailJobService.cs
+public interface IEmailJobService
+{
+    Task SendWelcomeEmailAsync(string userId);
+    Task SendPasswordResetAsync(string email);
+}
+
+// Services/Jobs/EmailJobService.cs
+public class EmailJobService : IEmailJobService
+{
+    private readonly IDbContextFactory<AppDbContext> _dbFactory;
+    private readonly IEmailSender _emailSender;
+
+    public EmailJobService(
+        IDbContextFactory<AppDbContext> dbFactory,
+        IEmailSender emailSender)
+    {
+        _dbFactory = dbFactory;
+        _emailSender = emailSender;
+    }
+
+    public async Task SendWelcomeEmailAsync(string userId)
+    {
+        // Use IDbContextFactory for background jobs
+        await using var db = await _dbFactory.CreateDbContextAsync();
+
+        var user = await db.Users.FindAsync(userId);
+        if (user == null) return;
+
+        await _emailSender.SendAsync(
+            user.Email,
+            "Welcome!",
+            $"Hello {user.Name}!");
+    }
+}
+
+// Register in DI
+builder.Services.AddScoped<IEmailJobService, EmailJobService>();
+```
+
+---
+
+## Retry & Error Handling
+
+### Custom Retry Attribute
+
+```csharp
+[AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 60, 300, 900 })]
+public async Task ProcessPaymentAsync(string paymentId)
+{
+    // Job logic with automatic retry on failure
+}
+```
+
+### Manual Retry Logic
+
+```csharp
+public async Task SendEmailWithRetryAsync(string email)
+{
+    int maxRetries = 3;
+    int attempt = 0;
+
+    while (attempt < maxRetries)
+    {
+        try
+        {
+            await _emailSender.SendAsync(email, "Subject", "Body");
+            return; // Success
+        }
+        catch (Exception ex)
+        {
+            attempt++;
+            if (attempt >= maxRetries)
+            {
+                // Log and give up
+                _logger.LogError(ex, "Failed to send email after {Attempts} attempts", maxRetries);
+                throw;
+            }
+
+            await Task.Delay(TimeSpan.FromSeconds(Math.Pow(2, attempt)));
+        }
+    }
+}
+```
+
+---
+
+## Dashboard Authorization
+
+```csharp
+// Filters/HangfireAuthorizationFilter.cs
+using Hangfire.Dashboard;
+
+public class HangfireAuthorizationFilter : IDashboardAuthorizationFilter
+{
+    public bool Authorize(DashboardContext context)
+    {
+        var httpContext = context.GetHttpContext();
+
+        // Allow in development
+        if (httpContext.Request.Host.Host.Contains("localhost"))
+            return true;
+
+        // Require authenticated user with Admin role
+        return httpContext.User.Identity?.IsAuthenticated == true
+            && httpContext.User.IsInRole("Admin");
+    }
+}
+```
+
+---
+
+## Best Practices
+
+### Avoid Scoped Services
+
+```csharp
+// ❌ BAD: Don't inject DbContext directly
+public class BadJobService
+{
+    private readonly AppDbContext _db; // Scoped service!
+
+    public BadJobService(AppDbContext db) => _db = db;
+}
+
+// ✅ GOOD: Use IDbContextFactory
+public class GoodJobService
+{
+    private readonly IDbContextFactory<AppDbContext> _dbFactory;
+
+    public GoodJobService(IDbContextFactory<AppDbContext> dbFactory)
+        => _dbFactory = dbFactory;
+
+    public async Task ProcessAsync()
+    {
+        await using var db = await _dbFactory.CreateDbContextAsync();
+        // Use db...
+    }
+}
+```
+
+### Idempotent Jobs
+
+```csharp
+public async Task ProcessOrderAsync(string orderId)
+{
+    await using var db = await _dbFactory.CreateDbContextAsync();
+
+    var order = await db.Orders.FindAsync(orderId);
+    if (order == null || order.Status == OrderStatus.Processed)
+    {
+        // Already processed or doesn't exist - skip
+        return;
+    }
+
+    // Process order...
+    order.Status = OrderStatus.Processed;
+    await db.SaveChangesAsync();
+}
+```
+
+---
+
+## Cron Schedule Examples
+
+```csharp
+Cron.Minutely()              // Every minute
+Cron.Hourly()                // Every hour at minute 0
+Cron.Daily()                 // Every day at 00:00 UTC
+Cron.Daily(14)               // Every day at 14:00 UTC
+Cron.Weekly()                // Every Sunday at 00:00 UTC
+Cron.Monthly()               // First day of month at 00:00 UTC
+Cron.Yearly()                // January 1st at 00:00 UTC
+
+// Custom cron
+"*/5 * * * *"                // Every 5 minutes
+"0 */2 * * *"                // Every 2 hours
+"0 9-17 * * 1-5"             // 9 AM to 5 PM, Mon-Fri
+```
+
+---
+
+## Monitoring & Troubleshooting
+
+### Dashboard Access
+
+Access the dashboard at `/hangfire` (configured in Program.cs).
+
+### Common Issues
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| Jobs not processing | Hangfire server not started | Ensure `AddHangfireServer()` is called |
+| DbContext errors | Using scoped DbContext | Use `IDbContextFactory` |
+| Jobs timing out | Long-running job | Split into smaller jobs with continuations |
+| Memory leaks | Not disposing DbContext | Use `await using` for DbContext |
+
+---
+
+## References
+
+- [Hangfire Documentation](https://docs.hangfire.io/)
+- [Hangfire Best Practices](https://docs.hangfire.io/en/latest/best-practices.html)
+- [Cron Expression Generator](https://crontab.guru/)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/backend/integrations/resend/resend-email.md

@@ -0,0 +1,385 @@
+# Resend Email Service Integration Standard
+
+> **Scope:** universal
+> **Layer:** 2 (on keyword)
+> **Keywords:** resend, email, transactional, smtp, sendgrid alternative
+> **Load When:** resend or transactional email keywords detected
+
+Modern transactional email service for developers, built for Next.js and .NET.
+
+---
+
+## Overview
+
+Resend provides:
+- Simple API for sending emails
+- React Email template support
+- Email tracking and analytics
+- Domain verification
+- Webhooks for delivery status
+- 100 free emails/day
+
+**Stack:** Universal (.NET + Next.js)
+
+---
+
+## Core Principles
+
+1. **API-First**: Use REST API, not SMTP
+2. **Type Safety**: Use official SDKs with TypeScript/C# types
+3. **Template-Based**: Use React Email for Next.js, Razor for .NET
+4. **Async**: Always send emails asynchronously
+5. **Monitor**: Track delivery status via webhooks
+
+---
+
+## Installation & Setup
+
+### Next.js Setup
+
+```bash
+npm install resend react-email
+```
+
+```typescript
+// lib/resend.ts
+import { Resend } from 'resend';
+
+export const resend = new Resend(process.env.RESEND_API_KEY);
+```
+
+### .NET Setup
+
+```bash
+dotnet add package Resend
+```
+
+```csharp
+// Program.cs
+using Resend;
+
+builder.Services.AddResend(options =>
+{
+    options.ApiKey = builder.Configuration["Resend:ApiKey"]!;
+});
+```
+
+### Environment Variables
+
+```bash
+# .env.local (Next.js) or appsettings.json (.NET)
+RESEND_API_KEY=re_...
+RESEND_FROM_EMAIL=noreply@yourdomain.com
+```
+
+---
+
+## Next.js Usage
+
+### React Email Template
+
+```tsx
+// emails/WelcomeEmail.tsx
+import { Html, Button, Container, Text } from '@react-email/components';
+
+interface WelcomeEmailProps {
+  name: string;
+  verificationUrl: string;
+}
+
+export default function WelcomeEmail({ name, verificationUrl }: WelcomeEmailProps) {
+  return (
+    <Html>
+      <Container>
+        <Text>Welcome, {name}!</Text>
+        <Button href={verificationUrl}>Verify Email</Button>
+      </Container>
+    </Html>
+  );
+}
+```
+
+### Send Email (API Route)
+
+```typescript
+// app/api/send-welcome/route.ts
+import { resend } from '@/lib/resend';
+import WelcomeEmail from '@/emails/WelcomeEmail';
+
+export async function POST(req: Request) {
+  const { email, name, verificationUrl } = await req.json();
+
+  try {
+    const { data, error } = await resend.emails.send({
+      from: 'MyApp <noreply@yourdomain.com>',
+      to: email,
+      subject: 'Welcome to MyApp!',
+      react: WelcomeEmail({ name, verificationUrl }),
+    });
+
+    if (error) {
+      return Response.json({ error }, { status: 500 });
+    }
+
+    return Response.json({ id: data.id });
+  } catch (error) {
+    return Response.json({ error: 'Failed to send email' }, { status: 500 });
+  }
+}
+```
+
+---
+
+## .NET Usage
+
+### Email Service Interface
+
+```csharp
+// Services/IEmailService.cs
+public interface IEmailService
+{
+    Task<string> SendWelcomeEmailAsync(string toEmail, string name);
+    Task<string> SendPasswordResetAsync(string toEmail, string resetUrl);
+}
+```
+
+### Email Service Implementation
+
+```csharp
+// Services/EmailService.cs
+using Resend;
+
+public class EmailService : IEmailService
+{
+    private readonly IResend _resend;
+    private readonly IConfiguration _config;
+
+    public EmailService(IResend resend, IConfiguration config)
+    {
+        _resend = resend;
+        _config = config;
+    }
+
+    public async Task<string> SendWelcomeEmailAsync(string toEmail, string name)
+    {
+        var message = new EmailMessage
+        {
+            From = _config["Resend:FromEmail"]!,
+            To = toEmail,
+            Subject = "Welcome!",
+            HtmlBody = $@"
+                <h1>Welcome, {name}!</h1>
+                <p>Thank you for joining us.</p>
+            "
+        };
+
+        var response = await _resend.EmailSendAsync(message);
+        return response.Id;
+    }
+
+    public async Task<string> SendPasswordResetAsync(string toEmail, string resetUrl)
+    {
+        var message = new EmailMessage
+        {
+            From = _config["Resend:FromEmail"]!,
+            To = toEmail,
+            Subject = "Reset Your Password",
+            HtmlBody = $@"
+                <h1>Password Reset</h1>
+                <p>Click the link below to reset your password:</p>
+                <a href=""{resetUrl}"">Reset Password</a>
+            "
+        };
+
+        var response = await _resend.EmailSendAsync(message);
+        return response.Id;
+    }
+}
+
+// Register in DI
+builder.Services.AddScoped<IEmailService, EmailService>();
+```
+
+---
+
+## Batch Emails
+
+### Next.js Batch Send
+
+```typescript
+// Send to multiple recipients
+const { data, error } = await resend.batch.send([
+  {
+    from: 'MyApp <noreply@yourdomain.com>',
+    to: 'user1@example.com',
+    subject: 'Notification',
+    react: NotificationEmail({ message: 'Update 1' }),
+  },
+  {
+    from: 'MyApp <noreply@yourdomain.com>',
+    to: 'user2@example.com',
+    subject: 'Notification',
+    react: NotificationEmail({ message: 'Update 2' }),
+  },
+]);
+```
+
+---
+
+## Webhooks for Delivery Status
+
+### Setup Webhook Endpoint
+
+```typescript
+// app/api/webhooks/resend/route.ts
+import { headers } from 'next/headers';
+import { createHmac } from 'crypto';
+
+export async function POST(req: Request) {
+  const body = await req.text();
+  const signature = headers().get('resend-signature');
+
+  // Verify webhook signature
+  const secret = process.env.RESEND_WEBHOOK_SECRET!;
+  const expectedSignature = createHmac('sha256', secret)
+    .update(body)
+    .digest('hex');
+
+  if (signature !== expectedSignature) {
+    return new Response('Invalid signature', { status: 401 });
+  }
+
+  const event = JSON.parse(body);
+
+  switch (event.type) {
+    case 'email.delivered':
+      await handleEmailDelivered(event.data);
+      break;
+    case 'email.bounced':
+      await handleEmailBounced(event.data);
+      break;
+    case 'email.complained':
+      await handleEmailComplained(event.data);
+      break;
+  }
+
+  return new Response('OK');
+}
+```
+
+---
+
+## Best Practices
+
+### Background Jobs (with Hangfire)
+
+```csharp
+// Don't block HTTP requests with email sending
+BackgroundJob.Enqueue<IEmailService>(
+    x => x.SendWelcomeEmailAsync(email, name));
+```
+
+### Rate Limiting
+
+```typescript
+// Implement rate limiting for email sends
+import { Ratelimit } from '@upstash/ratelimit';
+import { Redis } from '@upstash/redis';
+
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, '1 h'), // 10 emails per hour
+});
+
+const { success } = await ratelimit.limit(userId);
+if (!success) {
+  return Response.json({ error: 'Rate limit exceeded' }, { status: 429 });
+}
+
+await resend.emails.send({ ... });
+```
+
+### Retry Logic (.NET)
+
+```csharp
+using Polly;
+
+var retryPolicy = Policy
+    .Handle<HttpRequestException>()
+    .WaitAndRetryAsync(3, retryAttempt =>
+        TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));
+
+await retryPolicy.ExecuteAsync(async () =>
+{
+    await _resend.EmailSendAsync(message);
+});
+```
+
+---
+
+## Domain Verification
+
+1. Go to Resend Dashboard → Domains
+2. Add your domain (e.g., `yourdomain.com`)
+3. Add DNS records (SPF, DKIM, DMARC)
+4. Wait for verification (up to 72 hours)
+
+### DNS Records Example
+
+```
+TXT  @  v=spf1 include:resend.com ~all
+TXT  resend._domainkey  <DKIM_VALUE>
+TXT  _dmarc  v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
+```
+
+---
+
+## Common Email Templates
+
+### Order Confirmation
+
+```tsx
+export default function OrderConfirmation({ orderNumber, total, items }) {
+  return (
+    <Html>
+      <Container>
+        <Text>Order #{orderNumber} Confirmed</Text>
+        <Text>Total: ${total}</Text>
+        <ul>
+          {items.map(item => (
+            <li key={item.id}>{item.name} - ${item.price}</li>
+          ))}
+        </ul>
+      </Container>
+    </Html>
+  );
+}
+```
+
+### Magic Link Auth
+
+```tsx
+export default function MagicLink({ url, expiresIn }) {
+  return (
+    <Html>
+      <Container>
+        <Text>Sign in to your account</Text>
+        <Button href={url}>Sign In</Button>
+        <Text>This link expires in {expiresIn} minutes.</Text>
+      </Container>
+    </Html>
+  );
+}
+```
+
+---
+
+## References
+
+- [Resend Documentation](https://resend.com/docs)
+- [React Email](https://react.email/)
+- [Resend .NET SDK](https://github.com/resend/resend-dotnet)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*