prep docs and service updates

src/Excititor/StellaOps.Excititor.WebService/Controllers/GraphController.cs

@@ -0,0 +1,58 @@
+using System.Collections.Generic;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Options;
+using StellaOps.Excititor.WebService.Options;
+
+namespace StellaOps.Excititor.WebService.Controllers;
+
+[ApiController]
+[Route("v1/graph")]
+public class GraphController : ControllerBase
+{
+    private readonly GraphOptions _options;
+
+    public GraphController(IOptions<GraphOptions> options)
+    {
+        _options = options.Value;
+    }
+
+    [HttpPost("linkouts")]
+    public IActionResult Linkouts([FromBody] LinkoutRequest request)
+    {
+        if (request == null || request.Purls == null || request.Purls.Count == 0)
+        {
+            return BadRequest("purls are required");
+        }
+
+        if (request.Purls.Count > _options.MaxPurls)
+        {
+            return BadRequest($"purls limit exceeded (max {_options.MaxPurls})");
+        }
+
+        return StatusCode(503, "Graph linkouts pending storage integration.");
+    }
+
+    [HttpGet("overlays")]
+    public IActionResult Overlays([FromQuery(Name = "purl")] List<string> purls, [FromQuery] bool includeJustifications = false)
+    {
+        if (purls == null || purls.Count == 0)
+        {
+            return BadRequest("purl query parameter is required");
+        }
+
+        if (purls.Count > _options.MaxPurls)
+        {
+            return BadRequest($"purls limit exceeded (max {_options.MaxPurls})");
+        }
+
+        return StatusCode(503, "Graph overlays pending storage integration.");
+    }
+}
+
+public sealed record LinkoutRequest
+{
+    public string Tenant { get; init; } = string.Empty;
+    public List<string> Purls { get; init; } = new();
+    public bool IncludeJustifications { get; init; }
+    public bool IncludeProvenance { get; init; } = true;
+}

src/Excititor/StellaOps.Excititor.WebService/Options/GraphOptions.cs

@@ -0,0 +1,11 @@
+namespace StellaOps.Excititor.WebService.Options;
+
+/// <summary>
+/// Configuration for graph linkouts and overlays.
+/// </summary>
+public sealed class GraphOptions
+{
+    public int MaxPurls { get; set; } = 500;
+    public int MaxAdvisoriesPerPurl { get; set; } = 200;
+    public int OverlayTtlSeconds { get; set; } = 300;
+}

src/Excititor/StellaOps.Excititor.WebService/Program.usings.patchnote

@@ -0,0 +1,3 @@
+// NOTE: Unable to update Program.cs usings via apply_patch because of file size and PTY limits.
+// Desired additions:
+// using StellaOps.Excititor.WebService.Options;