Introduced the concept of standardized elements, which require less e…

…ffort to produce.
RyanLamansky · Aug 3, 2024 · a8e8360 · a8e8360
1 parent 8151443
commit a8e8360
Show file tree

Hide file tree

Showing 11 changed files with 193 additions and 7 deletions.
diff --git a/Examples/AspNetPageEmitter/Program.cs b/Examples/AspNetPageEmitter/Program.cs
@@ -1,5 +1,6 @@
 using HtmlUtilities;
 using HtmlUtilities.Validated;
+using HtmlUtilities.Validated.Standardized;
 
 var builder = WebApplication.CreateBuilder(args);
 
@@ -9,7 +10,7 @@
 
 app.Use((context, next) =>
 {
-    context.Response.GetTypedHeaders().CacheControl = new Microsoft.Net.Http.Headers.CacheControlHeaderValue()
+    context.Response.GetTypedHeaders().CacheControl = new()
     {
         Private = true,
         NoCache = true,
@@ -26,6 +27,7 @@ class TestDocument : IHtmlDocument
     ValidatedAttributeValue IHtmlDocument.Language => "en-us";
     ValidatedText IHtmlDocument.Title => "Hello World!";
     ValidatedAttributeValue IHtmlDocument.Description => "Test page for HTML Utilities";
+    IReadOnlyCollection<Style> IHtmlDocument.Styles { get; } = [new() { Content = string.Join('\n', File.ReadAllLines("styles.css")) }]; 
 
     Task IHtmlDocument.WriteBodyContentsAsync(HtmlWriter writer, CancellationToken cancellationToken)
     {

diff --git a/Examples/AspNetPageEmitter/styles.css b/Examples/AspNetPageEmitter/styles.css
@@ -0,0 +1,4 @@
+*, ::before, ::after {
+	box-sizing: border-box;
+	font-family: sans-serif;
+}
diff --git a/HtmlUtilities/AttributeWriter.cs b/HtmlUtilities/AttributeWriter.cs
@@ -13,6 +13,33 @@ public readonly struct AttributeWriter
 
     internal AttributeWriter(IBufferWriter<byte> writer) => this.writer = writer;
 
+    /// <summary>
+    /// Writes an attribute without a value.
+    /// </summary>
+    /// <param name="nameWithLeadingSpace">The name of the attribute, including a leading space to separate it.</param>
+    internal void Write(ReadOnlySpan<byte> nameWithLeadingSpace)
+    {
+        System.Diagnostics.Debug.Assert(nameWithLeadingSpace.Length >= 2 && nameWithLeadingSpace[0] == ' ');
+
+        writer.Write(nameWithLeadingSpace);
+    }
+
+    /// <summary>
+    /// Writes an attribute if a value is provided.
+    /// </summary>
+    /// <param name="nameWithLeadingSpace">The name of the attribute, including a leading space to separate it.</param>
+    /// <param name="value">The value to write. If null, the attribute is completely omitted.</param>
+    internal void Write(ReadOnlySpan<byte> nameWithLeadingSpace, ValidatedAttributeValue? value)
+    {
+        System.Diagnostics.Debug.Assert(nameWithLeadingSpace.Length >= 2 && nameWithLeadingSpace[0] == ' ');
+
+        if (!value.HasValue)
+            return;
+
+        writer.Write(nameWithLeadingSpace);
+        writer.Write(value.Value.value);
+    }
+
     /// <summary>
     /// Writes a validated attribute name with no value.
     /// </summary>

diff --git a/HtmlUtilities/HtmlDocumentExtensions.cs b/HtmlUtilities/HtmlDocumentExtensions.cs
@@ -24,8 +24,8 @@ public static Task WriteToAsync(this IHtmlDocument document, HttpContext context
         response.ContentType = "text/html; charset=utf-8";
         Span<char> cspNonceUtf16 = stackalloc char[32];
         System.Security.Cryptography.RandomNumberGenerator.GetHexString(cspNonceUtf16, true);
-        response.Headers.ContentSecurityPolicy = $"base-uri {request.Scheme}://{request.Host}/;default-src 'none';script-src 'unsafe-inline' 'nonce-{cspNonceUtf16}'";
-        // unsafe-inline only applies to browsers that don't support nonce. Can be removed someday.
+        response.Headers.ContentSecurityPolicy = $"base-uri {request.Scheme}://{request.Host}/;default-src 'unsafe-inline' 'nonce-{cspNonceUtf16}'";
+        // unsafe-inline only applies to browsers that don't support nonce. Can be removed when security scanners stop asking for it.
 
         var writer = context.Response.BodyWriter;
 
@@ -55,9 +55,17 @@ public static Task WriteToAsync(this IHtmlDocument document, HttpContext context
             writer.Write(">"u8);
         }
 
+        var htmlWriter = new HtmlWriter(writer, new Validated.ValidatedAttribute("nonce", cspNonceUtf16));
+
+        foreach (var link in document.Links ?? [])
+            link.Write(htmlWriter);
+
+        foreach (var style in document.Styles ?? [])
+            style.Write(htmlWriter);
+
         writer.Write("</head><body>"u8);
 
-        return document.WriteBodyContentsAsync(new HtmlWriter(writer, new Validated.ValidatedAttribute("nonce", cspNonceUtf16)), context.RequestAborted);
+        return document.WriteBodyContentsAsync(htmlWriter, context.RequestAborted);
 
         // HTML5 spec doesn't require </body></html>, so that simplifies things a bit here.
     }

diff --git a/HtmlUtilities/HtmlWriter.cs b/HtmlUtilities/HtmlWriter.cs
@@ -16,7 +16,7 @@ public sealed class HtmlWriter
         "</html>"u8.ToArray());
 
     private readonly IBufferWriter<byte> writer;
-    private readonly ValidatedAttribute cspNonce;
+    internal readonly ValidatedAttribute cspNonce;
 
     internal HtmlWriter(IBufferWriter<byte> writer)
         : this(writer, new ValidatedAttribute())
@@ -121,6 +121,32 @@ private static void WriteLessThan(IBufferWriter<byte> writer)
         writer.Advance(1);
     }
 
+    internal void WriteElement(ReadOnlySpan<byte> nameWithAngleBrackets, Action<AttributeWriter>? attributes = null, Action<HtmlWriter>? children = null)
+    {
+        var writer = this.writer;
+        var start = nameWithAngleBrackets;
+        Span<byte> end = stackalloc byte[nameWithAngleBrackets.Length + 1];
+        end[0] = (byte)'<';
+        end[1] = (byte)'/';
+        nameWithAngleBrackets[1..].CopyTo(end[2..]);
+
+        if (attributes is null)
+            writer.Write(start);
+        else
+        {
+            writer.Write(start[..^1]);
+
+            attributes(new AttributeWriter(this.writer));
+
+            WriteGreaterThan(writer);
+        }
+
+        if (children is not null)
+            children(this);
+
+        writer.Write(end);
+    }
+
     /// <summary>
     /// Writes a validated element with optional attributes and child content.
     /// </summary>
@@ -255,6 +281,18 @@ public void WriteElementSelfClosing(ValidatedElement element, Action<AttributeWr
         }
     }
 
+    internal void WriteElementSelfClosing(ReadOnlySpan<byte> nameWithAngleBrackets, Action<AttributeWriter>? attributes = null)
+    {
+        System.Diagnostics.Debug.Assert(nameWithAngleBrackets[0] == (byte)'<' && nameWithAngleBrackets[nameWithAngleBrackets.Length - 1] == (byte)'>');
+
+        writer.Write(nameWithAngleBrackets[..^1]);
+
+        if (attributes is not null)
+            attributes(new AttributeWriter(writer));
+
+        WriteGreaterThan(writer);
+    }
+
     /// <summary>
     /// Writes an element without an end tag.
     /// </summary>

diff --git a/HtmlUtilities/IHtmlDocument.cs b/HtmlUtilities/IHtmlDocument.cs
@@ -1,4 +1,5 @@
 using HtmlUtilities.Validated;
+using HtmlUtilities.Validated.Standardized;
 
 namespace HtmlUtilities;
 
@@ -25,6 +26,18 @@ public interface IHtmlDocument
     /// </summary>
     ValidatedAttributeValue Description => new();
 
+    /// <summary>
+    /// The document's "link" elements.
+    /// Empty by default.
+    /// </summary>
+    IReadOnlyCollection<Link> Links => [];
+
+    /// <summary>
+    /// The document's "link" elements.
+    /// Empty by default.
+    /// </summary>
+    IReadOnlyCollection<Style> Styles => [];
+
     /// <summary>
     /// Writes the content of an HTML document's body.
     /// </summary>

diff --git a/HtmlUtilities/Validated/StandardElement.cs b/HtmlUtilities/Validated/StandardElement.cs
@@ -0,0 +1,37 @@
+namespace HtmlUtilities.Validated;
+
+/// <summary>
+/// Provides friendly syntax for use of standardized HTML elements.
+/// </summary>
+public abstract class StandardElement
+{
+    // Global attribute list from https://html.spec.whatwg.org/#global-attributes.
+
+    /// <summary>
+    /// Uniquely identifies an element.
+    /// Source: https://dom.spec.whatwg.org/#concept-id
+    /// </summary>
+    public ValidatedAttributeValue? Id { get; set; }
+
+    /// <summary>
+    /// The title attribute represents advisory information for the element, such as would be appropriate for a tooltip.
+    /// Source: https://html.spec.whatwg.org/#attr-title
+    /// </summary>
+    public ValidatedAttributeValue? Title { get; set; }
+
+    private protected StandardElement()
+    {
+    }
+
+    internal abstract void Write(HtmlWriter writer);
+
+    /// <summary>
+    /// Writes global attributes to the provided <see cref="AttributeWriter"/>.
+    /// </summary>
+    /// <param name="writer">Receives the attributes.</param>
+    private protected void Write(AttributeWriter writer)
+    {
+        writer.Write(" id"u8, Id);
+        writer.Write(" title"u8, Title);
+    }
+}
diff --git a/HtmlUtilities/Validated/Standardized/Link.cs b/HtmlUtilities/Validated/Standardized/Link.cs
@@ -0,0 +1,28 @@
+namespace HtmlUtilities.Validated.Standardized;
+
+/// <summary>
+/// The HTML "link" element, from https://html.spec.whatwg.org/#the-link-element.
+/// </summary>
+public class Link : StandardElement
+{
+    /// <summary>
+    /// Relationship between the document containing the hyperlink and the destination resource.
+    /// </summary>
+    public string? Rel { get; set; }
+
+    /// <summary>
+    /// Address of the hyperlink.
+    /// </summary>
+    public string? Href { get; set; }
+
+    internal sealed override void Write(HtmlWriter writer)
+    {
+        writer.WriteElementSelfClosing("<link>"u8, attributes =>
+        {
+            base.Write(attributes);
+
+            attributes.Write(" rel"u8, Rel);
+            attributes.Write(" href"u8, Href);
+        });
+    }
+}
diff --git a/HtmlUtilities/Validated/Standardized/Style.cs b/HtmlUtilities/Validated/Standardized/Style.cs
@@ -0,0 +1,28 @@
+namespace HtmlUtilities.Validated.Standardized;
+
+/// <summary>
+/// Source: https://html.spec.whatwg.org/#the-style-element
+/// </summary>
+public class Style : StandardElement
+{
+    /// <summary>
+    /// Text that gives a conformant style sheet.
+    /// </summary>
+    public ValidatedText Content { get; set; }
+
+    /// <summary>
+    /// Applicable media.
+    /// </summary>
+    public ValidatedAttributeValue? Media { get; set; }
+
+    internal sealed override void Write(HtmlWriter writer)
+    {
+        writer.WriteElement("<style>"u8, attributes =>
+        {
+            Write(attributes);
+            attributes.Write(writer.cspNonce);
+
+            attributes.Write(" media"u8, Media);
+        }, children => children.WriteText(Content));
+    }
+}
diff --git a/HtmlUtilities/Validated/ValidatedElement.cs b/HtmlUtilities/Validated/ValidatedElement.cs
@@ -40,7 +40,7 @@ public ValidatedElement(ValidatedElementName name, params ValidatedAttribute[]?
     }
 
     // Internal fast path for known-safe tag pairs.
-    internal ValidatedElement(byte[] start, byte[] end)
+    internal ValidatedElement(ReadOnlyMemory<byte> start, ReadOnlyMemory<byte> end)
     {
         this.start = start;
         this.end = end;

diff --git a/HtmlUtilities/Validated/ValidatedText.cs b/HtmlUtilities/Validated/ValidatedText.cs
@@ -37,7 +37,8 @@ internal static void Validate(ReadOnlySpan<char> text, ref ArrayBuilder<byte> wr
         foreach (var codePoint in CodePoint.GetEnumerable(text))
         {
             var categories = codePoint.InfraCategories;
-            if ((categories & CodePointInfraCategory.AsciiWhitespace) == 0 && (categories & (CodePointInfraCategory.Surrogate | CodePointInfraCategory.Control)) != 0)
+            if ((categories & CodePointInfraCategory.AsciiWhitespace) == 0 &&
+                (categories & (CodePointInfraCategory.Surrogate | CodePointInfraCategory.Control | CodePointInfraCategory.NonCharacter)) != 0)
                 continue;
 
             switch (codePoint.Value)