WebmentionService - F# Azure Functions Guide

Expert AI assistant for the WebmentionService repository - an Azure Functions-based F# microservice that processes Webmentions (decentralized web notifications) and generates RSS feeds.

Repository Context

**WebmentionService** is a serverless Azure Functions application written in **F# (.NET 10.0)** that:

**Key characteristics:**

Step-by-Step Instructions

1. Environment Setup & Prerequisites

**CRITICAL**: This project requires **.NET 10.0 runtime**. Before any operations:

```bash

Check if .NET 10.0 is installed

dotnet --list-sdks | grep "10.0"

If missing, install it:

wget https://dot.net/v1/dotnet-install.sh -O /tmp/dotnet-install.sh

chmod +x /tmp/dotnet-install.sh

/tmp/dotnet-install.sh --channel 10.0

```

Verify installation before proceeding to any build operations.

2. Build & Restore Workflow

**Always follow this exact sequence:**

```bash

Step 1: Restore dependencies (ALWAYS run first)

dotnet restore

Expected: ~6-10 seconds, downloads NuGet packages

Step 2: Build (Debug)

dotnet build

Expected: ~2-8 seconds, outputs to bin/Debug/net10.0/

Step 3: Clean (when needed)

dotnet clean

Removes bin/ and obj/ directories

```

**Critical**: `dotnet restore` must complete successfully before `dotnet build` or the build will fail.

3. Understanding the Architecture

**Two main Azure Functions:**

1. **ReceiveWebmention** (`ReceiveWebmention.fs`)

- HTTP POST endpoint: `/inbox`

- Validates webmention format

- Stores in Azure Table Storage

- PartitionKey = target URL (encoded)

- RowKey = source URL (encoded)

2. **WebmentionToRss** (`WebmentionToRss.fs`)

- Timer-triggered: `0 0 3 * * *` (3 AM UTC daily)

- Reads from Table Storage

- Generates RSS feed XML

- Outputs to Azure Blob Storage

**Dependency chain (F# compilation order):**

```

Domain.fs → RssService.fs → Startup.fs → ReceiveWebmention.fs → WebmentionToRss.fs

```

4. Making Code Changes

**Before modifying code:**

1. **Never reorder files** in `WebmentionService.fsproj` - F# requires dependency order

2. **Understand F# patterns** used:

- Pattern matching (not if-else)

- Pipelines (`|>`) for transformations

- Immutable functions

3. **Preserve Azure bindings**:

- `[<FunctionName("Name")>]`

- `[<HttpTrigger(...)>]`

- `[<TimerTrigger(...)>]`

- `[<Table(...)>]`, `[<Blob(...)>]`

**After changes:**

```bash

dotnet build # Verify compilation

Review output for warnings/errors

```

5. Local Development Setup

Create `local.settings.json` (git-ignored):

```json

{

"IsEncrypted": false,

"Values": {

"AzureWebJobsStorage": "UseDevelopmentStorage=true",

"FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",

"PERSONAL_WEBSITE_HOSTNAMES": "localhost:3000,127.0.0.1:3000"

}

}

```

6. Pre-Deployment Validation

**No automated tests exist** - validate manually:

```bash

Step 1: Clean build

dotnet clean

dotnet restore

dotnet build

Step 2: Release build

dotnet publish --configuration Release

Output: bin/Release/net10.0/publish/

Step 3: Manual checklist

✓ No compilation errors

✓ Function attributes intact

✓ Azure bindings unchanged

✓ F# file order preserved in .fsproj

```

7. Deployment to Azure

```bash

Using Azure Functions Core Tools

func azure functionapp publish lqdevwebmentions-flex

```

**Note**: VS Code auto-runs `publish (functions)` task on deploy (configured in `.vscode/tasks.json`).

8. Common Issues & Solutions

**Issue: ".NET 10.0 not found"**

```

error : Framework: 'Microsoft.NETCore.App', version '10.0.0' (x64) not found

```

**Solution**: Run the .NET 10.0 installer command from Step 1.

**Issue: "local.settings.json missing"**

**Solution**: Create it manually using the template in Step 5.

**Issue: Build fails after file reorder**

**Solution**: Restore original file order in `.fsproj` - F# requires dependency order.

9. Configuration Reference

**Required Environment Variables (Azure/local.settings.json):**

| Variable | Value | Purpose |

|----------|-------|---------|

| `AzureWebJobsStorage` | Connection string | Table/Blob storage |

| `FUNCTIONS_WORKER_RUNTIME` | `dotnet-isolated` | Worker model |

| `PERSONAL_WEBSITE_HOSTNAMES` | Comma-separated | Allowed target domains |

Configured in `Startup.fs` via dependency injection.

10. VS Code Integration

**Pre-configured tasks** (`.vscode/tasks.json`):

**Dev container**: `.devcontainer.json` configured for Azure Functions development.

Key Dependencies

Quick Reference Commands

```bash

Full build cycle

dotnet restore && dotnet build

Clean rebuild

dotnet clean && dotnet restore && dotnet build

Release publish

dotnet publish --configuration Release

Deploy to Azure

func azure functionapp publish lqdevwebmentions-flex

```

Important Constraints

1. **No test suite** - all validation is manual

2. **No CI/CD** - no GitHub Actions configured

3. **F# file order matters** - never reorder in .fsproj

4. **Always restore before build** - dependency resolution required

5. **.NET 10.0 required** - project will not build on other versions

Additional Resources