| | | 1 | | using System.Management.Automation; |
| | | 2 | | using System.Management.Automation.Runspaces; |
| | | 3 | | using System.Diagnostics.CodeAnalysis; |
| | | 4 | | using Kestrun.Languages; |
| | | 5 | | using Kestrun.Models; |
| | | 6 | | using Kestrun.Runtime; |
| | | 7 | | using Microsoft.AspNetCore.Diagnostics; |
| | | 8 | | |
| | | 9 | | namespace Kestrun.Hosting.Options; |
| | | 10 | | /// <summary> |
| | | 11 | | /// Options for configuring Kestrun-style exception handling middleware. |
| | | 12 | | /// </summary> |
| | | 13 | | public sealed class ExceptionOptions : ExceptionHandlerOptions |
| | | 14 | | { |
| | | 15 | | /// <summary> |
| | | 16 | | /// Optional scripting options (e.g., PowerShell). If present, a script-based handler is used. |
| | | 17 | | /// </summary> |
| | | 18 | | private LanguageOptions? _languageOptions; |
| | | 19 | | |
| | | 20 | | /// <summary> |
| | | 21 | | /// Initializes a new instance of the <see cref="ExceptionOptions"/> class. |
| | | 22 | | /// </summary> |
| | | 23 | | /// <param name="host">The KestrunHost instance associated with these options.</param> |
| | | 24 | | /// <param name="developerExceptionPage">If true, enables the Developer Exception Page middleware with default optio |
| | | 25 | | [SetsRequiredMembers] |
| | 5 | 26 | | public ExceptionOptions(KestrunHost host, bool developerExceptionPage = false) |
| | | 27 | | { |
| | 5 | 28 | | ArgumentNullException.ThrowIfNull(host); |
| | 5 | 29 | | Host = host; |
| | 5 | 30 | | if (developerExceptionPage) |
| | | 31 | | { |
| | 1 | 32 | | DeveloperExceptionPageOptions = new DeveloperExceptionPageOptions(); |
| | | 33 | | } |
| | 5 | 34 | | } |
| | | 35 | | |
| | | 36 | | /// <summary> |
| | | 37 | | /// Optional Developer Exception Page options. If present, the Developer Exception Page middleware is used. |
| | | 38 | | /// </summary> |
| | 7 | 39 | | public DeveloperExceptionPageOptions? DeveloperExceptionPageOptions { get; set; } |
| | | 40 | | |
| | | 41 | | /// <summary> |
| | | 42 | | /// Optional scripting options (e.g., PowerShell). If present, a script-based handler is used. |
| | | 43 | | /// </summary> |
| | | 44 | | public LanguageOptions? LanguageOptions |
| | | 45 | | { |
| | 2 | 46 | | get => _languageOptions; |
| | | 47 | | set |
| | | 48 | | { |
| | 2 | 49 | | _languageOptions = value; |
| | 2 | 50 | | if (value is not null && ExceptionHandler is null) |
| | | 51 | | { |
| | 2 | 52 | | if (value.Language == Scripting.ScriptLanguage.PowerShell) |
| | | 53 | | { |
| | 0 | 54 | | throw new NotSupportedException("PowerShell is not supported for ExceptionOptions scripting at this |
| | | 55 | | } |
| | 2 | 56 | | var compiled = Host.CompileScript(value); |
| | | 57 | | |
| | 2 | 58 | | ExceptionHandler = BuildScriptExceptionHandler(this, compiled); |
| | | 59 | | } |
| | 2 | 60 | | } |
| | | 61 | | } |
| | | 62 | | |
| | | 63 | | /// <summary>Host is needed for runspace/bootstrap if using PowerShell.</summary> |
| | 8 | 64 | | public required KestrunHost Host { get; init; } |
| | | 65 | | |
| | | 66 | | // .NET 8 compatibility: ExceptionHandlerOptions in .NET 8 does not expose StatusCodeSelector. |
| | | 67 | | // Provide our own selector for net8.0; on net9.0+ prefer the base property. |
| | | 68 | | #if !NET9_0_OR_GREATER |
| | | 69 | | /// <summary> |
| | | 70 | | /// .NET 8: Optional custom status code selector for JSON/script fallback. |
| | | 71 | | /// Lets you map exception types to status codes. |
| | | 72 | | /// </summary> |
| | | 73 | | public Func<Exception, int>? LegacyStatusCodeSelector { get; set; } |
| | | 74 | | #endif |
| | | 75 | | |
| | | 76 | | private RequestDelegate BuildScriptExceptionHandler(ExceptionOptions o, RequestDelegate compiled) |
| | | 77 | | { |
| | 2 | 78 | | return async httpContext => |
| | 2 | 79 | | { |
| | 2 | 80 | | // Ensure a PS runspace exists if we're executing a PowerShell-based handler outside the normal PS middlewar |
| | 2 | 81 | | var needsBootstrap = o.LanguageOptions!.Language == Scripting.ScriptLanguage.PowerShell && |
| | 2 | 82 | | !httpContext.Items.ContainsKey(PowerShellDelegateBuilder.PS_INSTANCE_KEY); |
| | 2 | 83 | | |
| | 2 | 84 | | if (!needsBootstrap) |
| | 2 | 85 | | { |
| | 2 | 86 | | await compiled(httpContext); |
| | 2 | 87 | | return; |
| | 2 | 88 | | } |
| | 2 | 89 | | |
| | 0 | 90 | | var pool = o.Host.RunspacePool; // throws if not initialized |
| | 0 | 91 | | Runspace? runspace = null; |
| | 0 | 92 | | PowerShell? ps = null; |
| | 2 | 93 | | |
| | 2 | 94 | | try |
| | 2 | 95 | | { |
| | 0 | 96 | | runspace = await pool.AcquireAsync(httpContext.RequestAborted); |
| | 0 | 97 | | ps = PowerShell.Create(); |
| | 0 | 98 | | ps.Runspace = runspace; |
| | 2 | 99 | | |
| | 2 | 100 | | // Build Kestrun abstractions and inject for the script to consume |
| | 2 | 101 | | |
| | 0 | 102 | | var kr = new KestrunContext(Host, httpContext); |
| | 0 | 103 | | httpContext.Items[PowerShellDelegateBuilder.PS_INSTANCE_KEY] = ps; |
| | 0 | 104 | | httpContext.Items[PowerShellDelegateBuilder.KR_CONTEXT_KEY] = kr; |
| | 0 | 105 | | ps.Runspace.SessionStateProxy.SetVariable("Context", kr); |
| | 2 | 106 | | |
| | 0 | 107 | | await compiled(httpContext); |
| | 0 | 108 | | } |
| | 2 | 109 | | finally |
| | 2 | 110 | | { |
| | 0 | 111 | | ps?.Dispose(); |
| | 0 | 112 | | if (runspace is not null) |
| | 2 | 113 | | { |
| | 0 | 114 | | o.Host.RunspacePool.Release(runspace); |
| | 2 | 115 | | } |
| | 0 | 116 | | _ = httpContext.Items.Remove(PowerShellDelegateBuilder.PS_INSTANCE_KEY); |
| | 0 | 117 | | _ = httpContext.Items.Remove(PowerShellDelegateBuilder.KR_CONTEXT_KEY); |
| | 2 | 118 | | } |
| | 4 | 119 | | }; |
| | | 120 | | } |
| | | 121 | | |
| | | 122 | | /// <summary> |
| | | 123 | | /// Builds a JSON fallback handler that can be used if no script/inline handler is provided. |
| | | 124 | | /// </summary> |
| | | 125 | | /// <param name="useProblemDetails">Whether to use RFC 7807 ProblemDetails in the JSON fallback.</param> |
| | | 126 | | /// <param name="includeDetailsInDevelopment">Whether to include exception details in development.</param> |
| | | 127 | | /// <param name="compress">Whether to compress the JSON response.</param> |
| | | 128 | | /// <returns></returns> |
| | | 129 | | public void UseJsonExceptionHandler(bool useProblemDetails, bool includeDetailsInDevelopment, bool compress = false) |
| | | 130 | | { |
| | 1 | 131 | | ExceptionHandler = async httpContext => |
| | 1 | 132 | | { |
| | 1 | 133 | | // If the response already started, let the server bubble up |
| | 1 | 134 | | if (httpContext.Response.HasStarted) |
| | 1 | 135 | | { |
| | 1 | 136 | | // optional: log here |
| | 0 | 137 | | return; |
| | 1 | 138 | | } |
| | 1 | 139 | | |
| | 1 | 140 | | var env = httpContext.RequestServices.GetService(typeof(IHostEnvironment)) as IHostEnvironment; |
| | 1 | 141 | | var feature = httpContext.Features.Get<IExceptionHandlerFeature>(); |
| | 1 | 142 | | var ex = feature?.Error; |
| | 1 | 143 | | |
| | 1 | 144 | | #if NET9_0_OR_GREATER |
| | 1 | 145 | | var status = StatusCodeSelector?.Invoke(ex ?? new Exception("Unhandled exception")) |
| | 1 | 146 | | ?? StatusCodes.Status500InternalServerError; |
| | 1 | 147 | | #else |
| | 1 | 148 | | var status = LegacyStatusCodeSelector?.Invoke(ex ?? new Exception("Unhandled exception")) |
| | 1 | 149 | | ?? StatusCodes.Status500InternalServerError; |
| | 1 | 150 | | #endif |
| | 1 | 151 | | |
| | 1 | 152 | | var kestrunContext = new KestrunContext(Host, httpContext); |
| | 1 | 153 | | |
| | 1 | 154 | | // Always set the HTTP status first |
| | 1 | 155 | | kestrunContext.Response.StatusCode = status; |
| | 1 | 156 | | |
| | 1 | 157 | | // Choose the right media type |
| | 1 | 158 | | var contentType = useProblemDetails |
| | 1 | 159 | | ? "application/problem+json; charset=utf-8" |
| | 1 | 160 | | : "application/json; charset=utf-8"; |
| | 1 | 161 | | |
| | 1 | 162 | | // No-cache for error payloads |
| | 1 | 163 | | httpContext.Response.Headers.CacheControl = "no-store, no-cache, must-revalidate"; |
| | 1 | 164 | | httpContext.Response.Headers.Pragma = "no-cache"; |
| | 1 | 165 | | httpContext.Response.Headers.Expires = "0"; |
| | 1 | 166 | | |
| | 1 | 167 | | // Build body |
| | 1 | 168 | | var body = new Dictionary<string, object?> |
| | 1 | 169 | | { |
| | 1 | 170 | | ["status"] = status, |
| | 1 | 171 | | ["traceId"] = System.Diagnostics.Activity.Current?.Id ?? httpContext.TraceIdentifier, |
| | 1 | 172 | | ["instance"] = httpContext.Request.Path.HasValue ? httpContext.Request.Path.Value : "/" |
| | 1 | 173 | | }; |
| | 1 | 174 | | |
| | 1 | 175 | | if (useProblemDetails) |
| | 1 | 176 | | { |
| | 1 | 177 | | body["type"] = "about:blank"; // you can swap for a doc URL later |
| | 1 | 178 | | body["title"] = status switch |
| | 1 | 179 | | { |
| | 0 | 180 | | 400 => "Bad Request", |
| | 0 | 181 | | 401 => "Unauthorized", |
| | 0 | 182 | | 403 => "Forbidden", |
| | 0 | 183 | | 404 => "Not Found", |
| | 1 | 184 | | _ => "Internal Server Error" |
| | 1 | 185 | | }; |
| | 1 | 186 | | body["detail"] = includeDetailsInDevelopment && EnvironmentHelper.IsDevelopment() |
| | 1 | 187 | | ? ex?.ToString() |
| | 1 | 188 | | : ex?.Message; |
| | 1 | 189 | | } |
| | 1 | 190 | | else |
| | 1 | 191 | | { |
| | 0 | 192 | | body["error"] = true; |
| | 0 | 193 | | body["message"] = (includeDetailsInDevelopment && EnvironmentHelper.IsDevelopment()) |
| | 0 | 194 | | ? ex?.ToString() |
| | 0 | 195 | | : ex?.Message; |
| | 1 | 196 | | } |
| | 1 | 197 | | |
| | 1 | 198 | | // Note: `compress` means "compact JSON". Pretty-print when not compressing. |
| | 1 | 199 | | // Adjust the `5` (maxDepth) if your WriteJsonResponseAsync uses it that way. |
| | 1 | 200 | | await kestrunContext.Response.WriteJsonResponseAsync( |
| | 1 | 201 | | body, |
| | 1 | 202 | | 5, |
| | 1 | 203 | | compress, // compact when true |
| | 1 | 204 | | status, |
| | 1 | 205 | | contentType |
| | 1 | 206 | | ); |
| | 1 | 207 | | |
| | 1 | 208 | | await kestrunContext.Response.ApplyTo(httpContext.Response); |
| | 2 | 209 | | }; |
| | 1 | 210 | | } |
| | | 211 | | } |