Output encoding feature

nblumhardt · nblumhardt · commit dc89a23d9835 · 2023-08-22T13:26:11.000+10:00
diff --git a/src/Serilog.Expressions/Serilog.Expressions.csproj b/src/Serilog.Expressions/Serilog.Expressions.csproj
@@ -25,4 +25,5 @@
     <None Include="..\..\assets\icon.png" Pack="true" Visible="false" PackagePath="" />
   </ItemGroup>
 
+
 </Project>
diff --git a/src/Serilog.Expressions/Templates/Compilation/TemplateCompiler.cs b/src/Serilog.Expressions/Templates/Compilation/TemplateCompiler.cs
@@ -16,6 +16,7 @@
 using Serilog.Expressions.Ast;
 using Serilog.Expressions.Compilation;
 using Serilog.Templates.Ast;
+using Serilog.Templates.Encoding;
 using Serilog.Templates.Themes;
 
 namespace Serilog.Templates.Compilation;
@@ -24,39 +25,40 @@ static class TemplateCompiler
 {
     public static CompiledTemplate Compile(Template template,
         IFormatProvider? formatProvider, NameResolver nameResolver,
-        TemplateTheme theme)
+        TemplateTheme theme,
+        EncodedTemplateFactory encoder)
     {
         return template switch
         {
             LiteralText text => new CompiledLiteralText(text.Text, theme),
-            FormattedExpression { Expression: AmbientNameExpression { IsBuiltIn: true, PropertyName: BuiltInProperty.Level} } level => new CompiledLevelToken(
-                level.Format, level.Alignment, theme),
+            FormattedExpression { Expression: AmbientNameExpression { IsBuiltIn: true, PropertyName: BuiltInProperty.Level} } level =>
+                encoder.Wrap(new CompiledLevelToken(level.Format, level.Alignment, theme)),
             FormattedExpression
             {
                 Expression: AmbientNameExpression { IsBuiltIn: true, PropertyName: BuiltInProperty.Exception },
                 Alignment: null,
                 Format: null
-            } => new CompiledExceptionToken(theme),
+            } => encoder.Wrap(new CompiledExceptionToken(theme)),
             FormattedExpression
             {
                 Expression: AmbientNameExpression { IsBuiltIn: true, PropertyName: BuiltInProperty.Message },
                 Format: null
-            } message => new CompiledMessageToken(formatProvider, message.Alignment, theme),
-            FormattedExpression expression => new CompiledFormattedExpression(
+            } message => encoder.Wrap(new CompiledMessageToken(formatProvider, message.Alignment, theme)),
+            FormattedExpression expression => encoder.MakeCompiledFormattedExpression(
                 ExpressionCompiler.Compile(expression.Expression, formatProvider, nameResolver), expression.Format, expression.Alignment, formatProvider, theme),
-            TemplateBlock block => new CompiledTemplateBlock(block.Elements.Select(e => Compile(e, formatProvider, nameResolver, theme)).ToArray()),
+            TemplateBlock block => new CompiledTemplateBlock(block.Elements.Select(e => Compile(e, formatProvider, nameResolver, theme, encoder)).ToArray()),
             Conditional conditional => new CompiledConditional(
                 ExpressionCompiler.Compile(conditional.Condition, formatProvider, nameResolver),
-                Compile(conditional.Consequent, formatProvider, nameResolver, theme),
-                conditional.Alternative == null ? null : Compile(conditional.Alternative, formatProvider, nameResolver, theme)),
+                Compile(conditional.Consequent, formatProvider, nameResolver, theme, encoder),
+                conditional.Alternative == null ? null : Compile(conditional.Alternative, formatProvider, nameResolver, theme, encoder)),
             Repetition repetition => new CompiledRepetition(
                 ExpressionCompiler.Compile(repetition.Enumerable, formatProvider, nameResolver),
                 repetition.BindingNames.Length > 0 ? repetition.BindingNames[0] : null,
                 repetition.BindingNames.Length > 1 ? repetition.BindingNames[1] : null,
-                Compile(repetition.Body, formatProvider, nameResolver, theme),
-                repetition.Delimiter == null ? null : Compile(repetition.Delimiter, formatProvider, nameResolver, theme),
-                repetition.Alternative == null ? null : Compile(repetition.Alternative, formatProvider, nameResolver, theme)),
+                Compile(repetition.Body, formatProvider, nameResolver, theme, encoder),
+                repetition.Delimiter == null ? null : Compile(repetition.Delimiter, formatProvider, nameResolver, theme, encoder),
+                repetition.Alternative == null ? null : Compile(repetition.Alternative, formatProvider, nameResolver, theme, encoder)),
             _ => throw new NotSupportedException()
         };
     }
-}
+}
diff --git a/src/Serilog.Expressions/Templates/Compilation/TemplateFunctionNameResolver.cs b/src/Serilog.Expressions/Templates/Compilation/TemplateFunctionNameResolver.cs
@@ -17,6 +17,7 @@
 using Serilog.Expressions.Runtime;
 using Serilog.Templates.Ast;
 using Serilog.Templates.Compilation.UnreferencedProperties;
+using Serilog.Templates.Compilation.Unsafe;
 
 namespace Serilog.Templates.Compilation;
 
@@ -27,7 +28,8 @@ public static NameResolver Build(NameResolver? additionalNameResolver, Template
         var resolvers = new List<NameResolver>
         {
             new StaticMemberNameResolver(typeof(RuntimeOperators)),
-            new UnreferencedPropertiesFunction(template)
+            new UnreferencedPropertiesFunction(template),
+            new UnsafeOutputFunction()
         };
 
         if (additionalNameResolver != null)
diff --git a/src/Serilog.Expressions/Templates/Compilation/Unsafe/UnsafeOutputFunction.cs b/src/Serilog.Expressions/Templates/Compilation/Unsafe/UnsafeOutputFunction.cs
@@ -0,0 +1,49 @@
+﻿// Copyright © Serilog Contributors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Reflection;
+using Serilog.Events;
+using Serilog.Expressions;
+using Serilog.Templates.Encoding;
+
+namespace Serilog.Templates.Compilation.Unsafe;
+
+/// <summary>
+/// Marks an expression in a template as bypassing the output encoding mechanism.
+/// </summary>
+class UnsafeOutputFunction : NameResolver
+{
+    const string FunctionName = "unsafe";
+
+    public override bool TryResolveFunctionName(string name, [MaybeNullWhen(false)] out MethodInfo implementation)
+    {
+        if (name.Equals(FunctionName, StringComparison.OrdinalIgnoreCase))
+        {
+            implementation = typeof(UnsafeOutputFunction).GetMethod(nameof(Implementation),
+                BindingFlags.Static | BindingFlags.Public)!;
+            return true;
+        }
+
+        implementation = null;
+        return false;
+    }
+
+    // By convention, built-in functions accept and return nullable values.
+    // ReSharper disable once ReturnTypeCanBeNotNullable
+    public static LogEventPropertyValue? Implementation(LogEventPropertyValue? inner)
+    {
+        return new ScalarValue(new PreEncodedValue(inner));
+    }
+}
diff --git a/src/Serilog.Expressions/Templates/Encoding/EncodedCompiledTemplate.cs b/src/Serilog.Expressions/Templates/Encoding/EncodedCompiledTemplate.cs
@@ -0,0 +1,25 @@
+﻿using Serilog.Expressions;
+using Serilog.Templates.Compilation;
+
+namespace Serilog.Templates.Encoding
+{
+    class EncodedCompiledTemplate : CompiledTemplate
+    {
+        readonly CompiledTemplate _inner;
+        readonly TemplateOutputEncoder _encoder;
+
+        public EncodedCompiledTemplate(CompiledTemplate inner, TemplateOutputEncoder encoder)
+        {
+            _inner = inner;
+            _encoder = encoder;
+        }
+
+        public override void Evaluate(EvaluationContext ctx, TextWriter output)
+        {
+            var buffer = new StringWriter(output.FormatProvider);
+            _inner.Evaluate(ctx, buffer);
+            var encoded = _encoder.Encode(buffer.ToString());
+            output.Write(encoded);
+        }
+    }
+}
diff --git a/src/Serilog.Expressions/Templates/Encoding/EncodedTemplateFactory.cs b/src/Serilog.Expressions/Templates/Encoding/EncodedTemplateFactory.cs
@@ -0,0 +1,33 @@
+﻿using Serilog.Expressions;
+using Serilog.Parsing;
+using Serilog.Templates.Compilation;
+using Serilog.Templates.Themes;
+
+namespace Serilog.Templates.Encoding
+{
+    class EncodedTemplateFactory
+    {
+        readonly TemplateOutputEncoder? _encoder;
+
+        public EncodedTemplateFactory(TemplateOutputEncoder? encoder)
+        {
+            _encoder = encoder;
+        }
+        
+        public CompiledTemplate Wrap(CompiledTemplate inner)
+        {
+            if (_encoder == null)
+                return inner;
+
+            return new EncodedCompiledTemplate(inner, _encoder);
+        }
+        
+        public CompiledTemplate MakeCompiledFormattedExpression(Evaluatable expression, string? format, Alignment? alignment, IFormatProvider? formatProvider, TemplateTheme theme)
+        {
+            if (_encoder == null)
+                return new CompiledFormattedExpression(expression, format, alignment, formatProvider, theme);
+            
+            return new EscapableEncodedCompiledFormattedExpression(expression, format, alignment, formatProvider, theme, _encoder);
+        }
+    }
+}
diff --git a/src/Serilog.Expressions/Templates/Encoding/EscapableEncodedCompiledFormattedExpression.cs b/src/Serilog.Expressions/Templates/Encoding/EscapableEncodedCompiledFormattedExpression.cs
@@ -0,0 +1,56 @@
+﻿using Serilog.Events;
+using Serilog.Expressions;
+using Serilog.Expressions.Runtime;
+using Serilog.Parsing;
+using Serilog.Templates.Compilation;
+using Serilog.Templates.Themes;
+
+namespace Serilog.Templates.Encoding
+{
+    class EscapableEncodedCompiledFormattedExpression : CompiledTemplate
+    {
+        static int _nextSubstituteLocalNameSuffix;
+        readonly string _substituteLocalName = $"%sub{Interlocked.Increment(ref _nextSubstituteLocalNameSuffix)}";
+        readonly Evaluatable _expression;
+        readonly TemplateOutputEncoder _encoder;
+        readonly CompiledFormattedExpression _inner;
+
+        public EscapableEncodedCompiledFormattedExpression(Evaluatable expression, string? format, Alignment? alignment, IFormatProvider? formatProvider, TemplateTheme theme, TemplateOutputEncoder encoder)
+        {
+            _expression = expression;
+            _encoder = encoder;
+            _inner = new CompiledFormattedExpression(GetSubstituteLocalValue, format, alignment, formatProvider, theme);
+        }
+
+        LogEventPropertyValue? GetSubstituteLocalValue(EvaluationContext context)
+        {
+            return Locals.TryGetValue(context.Locals, _substituteLocalName, out var computed)
+                ? computed
+                : null;
+        }
+
+        public override void Evaluate(EvaluationContext ctx, TextWriter output)
+        {
+            var value = _expression(ctx);
+            
+            if (value is ScalarValue { Value: PreEncodedValue pv })
+            {
+                var rawContext = pv.Inner == null ?
+                    new EvaluationContext(ctx.LogEvent) :
+                    new EvaluationContext(ctx.LogEvent, Locals.Set(ctx.Locals, _substituteLocalName, pv.Inner));
+                _inner.Evaluate(rawContext, output);
+                return;
+            }
+
+            var buffer = new StringWriter(output.FormatProvider);
+            
+            var bufferedContext = value == null
+                ? ctx
+                : new EvaluationContext(ctx.LogEvent, Locals.Set(ctx.Locals, _substituteLocalName, value));
+
+            _inner.Evaluate(bufferedContext, buffer);
+            var encoded = _encoder.Encode(buffer.ToString());
+            output.Write(encoded);
+        }
+    }
+}
diff --git a/src/Serilog.Expressions/Templates/Encoding/PreEncodedValue.cs b/src/Serilog.Expressions/Templates/Encoding/PreEncodedValue.cs
@@ -0,0 +1,21 @@
+﻿using Serilog.Events;
+
+namespace Serilog.Templates.Encoding
+{
+    class PreEncodedValue
+    {
+        public LogEventPropertyValue? Inner { get; }
+
+        public PreEncodedValue(LogEventPropertyValue? inner)
+        {
+            Inner = inner;
+        }
+
+        public override string ToString()
+        {
+            // This code path indicates that the template expects encoding to be performed, but no encoder is
+            // registered (probably a bad situation to be in).
+            throw new InvalidOperationException("No output encoder is registered.");
+        }
+    }
+}
diff --git a/src/Serilog.Expressions/Templates/Encoding/TemplateOutputEncoder.cs b/src/Serilog.Expressions/Templates/Encoding/TemplateOutputEncoder.cs
@@ -0,0 +1,15 @@
+﻿namespace Serilog.Templates.Encoding
+{
+    /// <summary>
+    /// An encoder applied to the output substituted into template holes.
+    /// </summary>
+    public abstract class TemplateOutputEncoder
+    {
+        /// <summary>
+        /// Encode <paramref name="value" />.
+        /// </summary>
+        /// <param name="value">The raw template output to encode.</param>
+        /// <returns>The encoded output.</returns>
+        public abstract string Encode(string value);
+    }
+}
diff --git a/src/Serilog.Expressions/Templates/ExpressionTemplate.cs b/src/Serilog.Expressions/Templates/ExpressionTemplate.cs
@@ -18,6 +18,7 @@
 using Serilog.Formatting;
 using Serilog.Templates.Compilation;
 using Serilog.Templates.Compilation.NameResolution;
+using Serilog.Templates.Encoding;
 using Serilog.Templates.Parsing;
 using Serilog.Templates.Themes;
 
@@ -43,7 +44,7 @@ public static bool TryParse(
         [MaybeNullWhen(true)] out string error)
     {
         if (template == null) throw new ArgumentNullException(nameof(template));
-        return TryParse(template, null, null, null, false, out result, out error);
+        return TryParse(template, null, null, null, false, null, out result, out error);
     }
 
     /// <summary>
@@ -59,13 +60,15 @@ public static bool TryParse(
     /// with which to resolve function names that appear in the template.</param>
     /// <param name="applyThemeWhenOutputIsRedirected">Apply <paramref name="theme"/> even when
     /// <see cref="System.Console.IsOutputRedirected"/> or <see cref="Console.IsErrorRedirected"/> returns <c>true</c>.</param>
+    /// <param name="encoder">Optionally, an encoder to apply to output substituted into template holes.</param>
     /// <returns><c langword="true">true</c> if the template was well-formed.</returns>
     public static bool TryParse(
         string template,
         IFormatProvider? formatProvider,
         NameResolver? nameResolver,
         TemplateTheme? theme,
         bool applyThemeWhenOutputIsRedirected,
+        TemplateOutputEncoder? encoder,
         [MaybeNullWhen(false)] out ExpressionTemplate result,
         [MaybeNullWhen(true)] out string error)
     {
@@ -85,7 +88,8 @@ public static bool TryParse(
                 planned,
                 formatProvider,
                 TemplateFunctionNameResolver.Build(nameResolver, planned),
-                SelectTheme(theme, applyThemeWhenOutputIsRedirected)));
+                SelectTheme(theme, applyThemeWhenOutputIsRedirected),
+                new EncodedTemplateFactory(encoder)));
 
         return true;
     }
@@ -106,12 +110,14 @@ public static bool TryParse(
     /// <param name="theme">Optionally, an ANSI theme to apply to the template output.</param>
     /// <param name="applyThemeWhenOutputIsRedirected">Apply <paramref name="theme"/> even when
     /// <see cref="Console.IsOutputRedirected"/> or <see cref="Console.IsErrorRedirected"/> returns <c>true</c>.</param>
+    /// <param name="encoder">Optionally, an encoder to apply to output substituted into template holes.</param>
     public ExpressionTemplate(
         string template,
         IFormatProvider? formatProvider = null,
         NameResolver? nameResolver = null,
         TemplateTheme? theme = null,
-        bool applyThemeWhenOutputIsRedirected = false)
+        bool applyThemeWhenOutputIsRedirected = false,
+        TemplateOutputEncoder? encoder = null)
     {
         if (template == null) throw new ArgumentNullException(nameof(template));
 
@@ -125,7 +131,8 @@ public ExpressionTemplate(
             planned,
             formatProvider,
             TemplateFunctionNameResolver.Build(nameResolver, planned),
-            SelectTheme(theme, applyThemeWhenOutputIsRedirected));
+            SelectTheme(theme, applyThemeWhenOutputIsRedirected),
+            new EncodedTemplateFactory(encoder));
     }
 
     static TemplateTheme SelectTheme(TemplateTheme? supplied, bool applyThemeWhenOutputIsRedirected)
diff --git a/test/Serilog.Expressions.Tests/Cases/template-encoding-cases.asv b/test/Serilog.Expressions.Tests/Cases/template-encoding-cases.asv
@@ -0,0 +1,8 @@
+{@m}                              ⇶ (Hello, nblumhardt!)
+{'world'}!                        ⇶ (world)!
+{unsafe('world')}!                ⇶ world!
+{substring('world', 0, 2)}!       ⇶ (wo)!
+|{somethingnothere}|              ⇶ |()|
+{#if true}x{'A'}x{#end}           ⇶ x(A)x
+{#each a in [1,2,3]}<{a}>{#delimit},{#end}           ⇶ <(1)>,<(2)>,<(3)>
+{ {name: 'world' } }!             ⇶ ({"name":"world"})!
diff --git a/test/Serilog.Expressions.Tests/Support/ParenthesizingEncoder.cs b/test/Serilog.Expressions.Tests/Support/ParenthesizingEncoder.cs
@@ -0,0 +1,11 @@
+﻿using Serilog.Templates.Encoding;
+
+namespace Serilog.Expressions.Tests.Support;
+
+public class ParenthesizingEncoder : TemplateOutputEncoder
+{
+    public override string Encode(string value)
+    {
+        return $"({value})";
+    }
+}
diff --git a/test/Serilog.Expressions.Tests/Support/StringHashPrefixingTheme.cs b/test/Serilog.Expressions.Tests/Support/StringHashPrefixingTheme.cs
@@ -0,0 +1,11 @@
+using Serilog.Templates.Themes;
+
+namespace Serilog.Expressions.Tests.Support;
+
+static class StringHashPrefixingTheme
+{
+    public static readonly TemplateTheme Instance = new(new Dictionary<TemplateThemeStyle, string>
+    {
+        [TemplateThemeStyle.String] = "#"
+    });
+}
diff --git a/test/Serilog.Expressions.Tests/TemplateEncodingTests.cs b/test/Serilog.Expressions.Tests/TemplateEncodingTests.cs
diff --git a/test/Serilog.Expressions.Tests/TemplateParserTests.cs b/test/Serilog.Expressions.Tests/TemplateParserTests.cs
