Functions host to take a customer specified port in Custom Handler scenario (#11408)

surgupta-msft · fabiocav · commit fd1bae8bbe1a · 2025-10-20T11:35:24.000-07:00
diff --git a/release_notes.md b/release_notes.md
@@ -6,3 +6,6 @@
 -->
 - Update Python Worker Version to [4.40.2](https://github.com/Azure/azure-functions-python-worker/releases/tag/4.40.2)
 - Add JitTrace Files for v4.1044
+- Remove duplicate function names from sync triggers payload(#11371)
+- Avoid emitting empty tag values for health check metrics (#11393)
+- Functions host to take a customer specified port in Custom Handler scenario (#11408)
diff --git a/sample/CustomHandler/host.json b/sample/CustomHandler/host.json
@@ -5,6 +5,7 @@
     "description": {
       "defaultExecutablePath": "node",
       "arguments": [ "server.js" ]
-    }
+    },
+    "port": "3456"
   }
 }
diff --git a/src/WebJobs.Script.WebHost/WebJobsScriptHostService.cs b/src/WebJobs.Script.WebHost/WebJobsScriptHostService.cs
@@ -630,7 +630,7 @@ public async Task RestartHostAsync(string reason, CancellationToken cancellation
                         // If we are running in development mode with core tools, do not overlap the restarts.
                         // Overlapping restarts are problematic when language worker processes are listening
                         // to the same debug port
-                        if (ShouldEnforceSequentialRestart())
+                        if (ShouldEnforceSequentialRestart(previousHost))
                         {
                             stopTask = Orphan(previousHost, cancellationToken);
                             await stopTask;
@@ -683,16 +683,11 @@ private static void NotifyHostStopping(IHost previousHost)
             dispatcher?.PreShutdown();
         }
 
-        internal bool ShouldEnforceSequentialRestart()
+        internal bool ShouldEnforceSequentialRestart(IHost host = null)
         {
-            var sequentialRestartSetting = _config.GetSection(ConfigurationSectionNames.SequentialJobHostRestart);
-            if (sequentialRestartSetting != null)
-            {
-                bool.TryParse(sequentialRestartSetting.Value, out bool enforceSequentialOrder);
-                return enforceSequentialOrder;
-            }
-
-            return false;
+            var options = host?.Services?.GetService<IOptions<ScriptHostRecycleOptions>>().Value;
+            options ??= ScriptHostRecycleOptions.Create(_config);
+            return options.SequentialHostRestartRequired;
         }
 
         private void OnHostInitializing(object sender, EventArgs e)
diff --git a/src/WebJobs.Script/Config/ScriptHostRecycleOptions.cs b/src/WebJobs.Script/Config/ScriptHostRecycleOptions.cs
@@ -0,0 +1,48 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Azure.WebJobs.Hosting;
+using Microsoft.Azure.WebJobs.Script.Configuration;
+using Microsoft.Extensions.Configuration;
+
+namespace Microsoft.Azure.WebJobs.Script
+{
+    /// <summary>
+    /// Options that control Script Host recycling behavior.
+    /// </summary>
+    public sealed class ScriptHostRecycleOptions : IOptionsFormatter
+    {
+        /// <summary>
+        /// Gets or sets a value indicating whether sequential host restarts are required.
+        /// </summary>
+        public bool SequentialHostRestartRequired { get; set; }
+
+        public static ScriptHostRecycleOptions Create(IConfiguration configuration)
+        {
+            ScriptHostRecycleOptions options = new();
+            options.Configure(configuration);
+            return options;
+        }
+
+        public string Format()
+        {
+            return JsonSerializer.Serialize(this, typeof(ScriptHostRecycleOptions), ScriptHostRecycleOptionsJsonContext.Default);
+        }
+
+        internal void Configure(IConfiguration configuration)
+        {
+            var sequentialRestartSetting = configuration.GetSection(ConfigurationSectionNames.SequentialJobHostRestart);
+            if (sequentialRestartSetting != null)
+            {
+                _ = bool.TryParse(sequentialRestartSetting.Value, out bool enforceSequentialOrder);
+                SequentialHostRestartRequired = enforceSequentialOrder;
+            }
+        }
+    }
+
+    [JsonSourceGenerationOptions(GenerationMode = JsonSourceGenerationMode.Serialization, WriteIndented = true)]
+    [JsonSerializable(typeof(ScriptHostRecycleOptions))]
+    internal partial class ScriptHostRecycleOptionsJsonContext : JsonSerializerContext;
+}
diff --git a/src/WebJobs.Script/Config/ScriptHostRecycleOptionsSetup.cs b/src/WebJobs.Script/Config/ScriptHostRecycleOptionsSetup.cs
@@ -0,0 +1,34 @@
+// Copyright (c) .NET Foundation. All rights reserved.
+// Licensed under the MIT License. See License.txt in the project root for license information.
+
+using System;
+using Microsoft.Azure.WebJobs.Script.Workers.Http;
+using Microsoft.Extensions.Configuration;
+using Microsoft.Extensions.Options;
+
+namespace Microsoft.Azure.WebJobs.Script.Configuration
+{
+    internal sealed class ScriptHostRecycleOptionsSetup : IConfigureOptions<ScriptHostRecycleOptions>
+    {
+        private readonly IOptions<HttpWorkerOptions> _httpWorkerOptions;
+        private readonly IConfiguration _configuration;
+
+        public ScriptHostRecycleOptionsSetup(
+            IOptions<HttpWorkerOptions> httpWorkerOptions, IConfiguration configuration)
+        {
+            _httpWorkerOptions = httpWorkerOptions ?? throw new ArgumentNullException(nameof(httpWorkerOptions));
+            _configuration = configuration ?? throw new ArgumentNullException(nameof(configuration));
+        }
+
+        public void Configure(ScriptHostRecycleOptions options)
+        {
+            options.Configure(_configuration);
+
+            // Enforcing sequential host restarts when a user-specified custom handler port is configured to prevent multiple processes from attempting to bind to the same port concurrently.
+            if (_httpWorkerOptions.Value.IsPortManuallySet)
+            {
+                options.SequentialHostRestartRequired = true;
+            }
+        }
+    }
+}
diff --git a/src/WebJobs.Script/ScriptHostBuilderExtensions.cs b/src/WebJobs.Script/ScriptHostBuilderExtensions.cs
@@ -339,6 +339,7 @@ public static IHostBuilder AddScriptHostCore(this IHostBuilder builder, ScriptAp
                 services.ConfigureOptions<JobHostFunctionTimeoutOptionsSetup>();
                 services.AddOptions<WorkerConcurrencyOptions>();
                 services.ConfigureOptions<HttpWorkerOptionsSetup>();
+                services.ConfigureOptions<ScriptHostRecycleOptionsSetup>();
                 services.ConfigureOptions<ManagedDependencyOptionsSetup>();
                 services.AddOptions<FunctionResultAggregatorOptions>()
                     .Configure<IConfiguration>((o, c) =>
diff --git a/src/WebJobs.Script/WorkerUtilities.cs b/src/WebJobs.Script/WorkerUtilities.cs
@@ -1,4 +1,4 @@
-﻿// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the MIT License. See License.txt in the project root for license information.
 
 using System.Net;
@@ -17,5 +17,37 @@ public static int GetUnusedTcpPort()
                 return port;
             }
         }
+
+        /// <summary>
+        /// Determines whether the specified port is available.
+        /// </summary>
+        internal static bool CanBindToPort(int port)
+        {
+            // Try to bind to the port using IPv6 dual mode socket to cover both IPv4 and IPv6.
+            using var tcpSocket = new Socket(AddressFamily.InterNetworkV6, SocketType.Stream, ProtocolType.Tcp) { DualMode = true };
+            try
+            {
+                tcpSocket.Bind(new IPEndPoint(IPAddress.IPv6Any, port));
+                return true;
+            }
+            catch (SocketException se) when (se.SocketErrorCode == SocketError.AddressAlreadyInUse)
+            {
+                return false;
+            }
+            catch
+            {
+                // Fall back to IPv4 only socket if IPv6 is not supported on the platform.
+                using var tcpSocketAny = new Socket(AddressFamily.InterNetwork, SocketType.Stream, ProtocolType.Tcp);
+                try
+                {
+                    tcpSocketAny.Bind(new IPEndPoint(IPAddress.Any, port));
+                    return true;
+                }
+                catch
+                {
+                    return false;
+                }
+            }
+        }
     }
 }
diff --git a/src/WebJobs.Script/Workers/Http/Configuration/HttpWorkerOptions.cs b/src/WebJobs.Script/Workers/Http/Configuration/HttpWorkerOptions.cs
@@ -10,13 +10,44 @@ namespace Microsoft.Azure.WebJobs.Script.Workers.Http
 {
     public class HttpWorkerOptions : IOptionsFormatter
     {
+        private int? _port;
+
         public CustomHandlerType Type { get; set; }
 
         public HttpWorkerDescription Description { get; set; }
 
         public WorkerProcessArguments Arguments { get; set; }
 
-        public int Port { get; set; }
+        public int Port
+        {
+            get
+            {
+                if (_port is null)
+                {
+                    _port = WorkerUtilities.GetUnusedTcpPort(); // Will always be realized during Options setup.
+                    IsPortManuallySet = false;
+                }
+
+                return _port.Value;
+            }
+
+            set
+            {
+                // During dynamic allocation of port, the get method will be called before set method and _port will be assigned dynamically.
+                // Adding a check here to make sure we don't override IsPortManuallySet flag in that case.
+                if (_port != value)
+                {
+                    IsPortManuallySet = true;
+                    _port = value;
+                }
+            }
+        }
+
+        /// <summary>
+        /// Gets a value indicating whether the <see cref="Port"/> property value is taken from configuration.
+        /// True value indicates that the host will use the configured port value rather than allocating a dynamic port.
+        /// </summary>
+        public bool IsPortManuallySet { get; private set; }
 
         /// <summary>
         /// Gets or sets a value indicating whether the host will forward the request to the worker process.
diff --git a/src/WebJobs.Script/Workers/Http/Configuration/HttpWorkerOptionsSetup.cs b/src/WebJobs.Script/Workers/Http/Configuration/HttpWorkerOptionsSetup.cs
@@ -15,7 +15,7 @@
 
 namespace Microsoft.Azure.WebJobs.Script.Workers.Http
 {
-    internal class HttpWorkerOptionsSetup : IConfigureOptions<HttpWorkerOptions>
+    internal class HttpWorkerOptionsSetup : IConfigureOptions<HttpWorkerOptions>, IValidateOptions<HttpWorkerOptions>
     {
         private readonly IEnvironment _environment;
         private IConfiguration _configuration;
@@ -130,7 +130,6 @@ private void ConfigureWorkerDescription(HttpWorkerOptions options, IConfiguratio
 
             options.Arguments.ExecutableArguments.AddRange(options.Description.Arguments);
             options.Arguments.WorkerArguments.AddRange(options.Description.WorkerArguments);
-            options.Port = WorkerUtilities.GetUnusedTcpPort();
         }
 
         private static List<string> GetArgumentList(IConfigurationSection workerConfigSection, string argumentSectionName)
@@ -148,5 +147,22 @@ private static List<string> GetArgumentList(IConfigurationSection workerConfigSe
             }
             return null;
         }
+
+        public ValidateOptionsResult Validate(string name, HttpWorkerOptions options)
+        {
+            if (options.IsPortManuallySet)
+            {
+                var port = options.Port;
+
+                if (port == 0 || !WorkerUtilities.CanBindToPort(port))
+                {
+                    throw new HostConfigurationException($"Unable to bind to port {port} specified in configuration. Please specify a different port or remove the section to allow dynamic binding of port.");
+                }
+
+                _logger.LogInformation("Using port {port} specified via configuration for custom handler.", port);
+            }
+
+            return ValidateOptionsResult.Success;
+        }
     }
 }
diff --git a/test/WebJobs.Script.Tests.Integration/WebHostEndToEnd/SamplesEndToEndTests_CustomHandler.cs b/test/WebJobs.Script.Tests.Integration/WebHostEndToEnd/SamplesEndToEndTests_CustomHandler.cs
@@ -1,4 +1,4 @@
-﻿// Copyright (c) .NET Foundation. All rights reserved.
+// Copyright (c) .NET Foundation. All rights reserved.
 // Licensed under the MIT License. See License.txt in the project root for license information.
 
 using System;
@@ -9,6 +9,8 @@
 using System.Threading.Tasks;
 using Microsoft.Azure.WebJobs.Script.Config;
 using Microsoft.Azure.WebJobs.Script.Workers.Rpc;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Options;
 using Microsoft.WebJobs.Script.Tests;
 using Newtonsoft.Json.Linq;
 using Xunit;
@@ -50,6 +52,9 @@ private async Task InvokeHttpTrigger(string functionName)
             var response = await _fixture.Host.HttpClient.SendAsync(request);
             Assert.Equal(HttpStatusCode.OK, response.StatusCode);
 
+            var options = _fixture.Host?.JobHostServices?.GetService<IOptions<ScriptHostRecycleOptions>>();
+            Assert.True(options.Value.SequentialHostRestartRequired);
+
             string responseContent = await response.Content.ReadAsStringAsync();
             JObject res = JObject.Parse(responseContent);
             Assert.True(res["functionName"].ToString().StartsWith($"api/{functionName}"));
diff --git a/test/WebJobs.Script.Tests/Configuration/HttpWorkerOptionsSetupTests.cs b/test/WebJobs.Script.Tests/Configuration/HttpWorkerOptionsSetupTests.cs
diff --git a/test/WebJobs.Script.Tests/Configuration/ScriptHostRecycleOptionsSetupTests.cs b/test/WebJobs.Script.Tests/Configuration/ScriptHostRecycleOptionsSetupTests.cs
diff --git a/test/WebJobs.Script.Tests/Configuration/ScriptHostRecycleOptionsTests.cs b/test/WebJobs.Script.Tests/Configuration/ScriptHostRecycleOptionsTests.cs

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`"description": {`
`6`	`6`	`"defaultExecutablePath": "node",`
`7`	`7`	`"arguments": [ "server.js" ]`
`8`		`- }`
	`8`	`+ },`
	`9`	`+ "port": "3456"`
`9`	`10`	`}`
`10`	`11`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,7 +15,7 @@`
`15`	`15`
`16`	`16`	`namespace Microsoft.Azure.WebJobs.Script.Workers.Http`
`17`	`17`	`{`
`18`		`- internal class HttpWorkerOptionsSetup : IConfigureOptions<HttpWorkerOptions>`
	`18`	`+ internal class HttpWorkerOptionsSetup : IConfigureOptions<HttpWorkerOptions>, IValidateOptions<HttpWorkerOptions>`
`19`	`19`	`{`
`20`	`20`	`private readonly IEnvironment _environment;`
`21`	`21`	`private IConfiguration _configuration;`
`@@ -130,7 +130,6 @@ private void ConfigureWorkerDescription(HttpWorkerOptions options, IConfiguratio`
`130`	`130`
`131`	`131`	`options.Arguments.ExecutableArguments.AddRange(options.Description.Arguments);`
`132`	`132`	`options.Arguments.WorkerArguments.AddRange(options.Description.WorkerArguments);`
`133`		`- options.Port = WorkerUtilities.GetUnusedTcpPort();`
`134`	`133`	`}`
`135`	`134`
`136`	`135`	`private static List<string> GetArgumentList(IConfigurationSection workerConfigSection, string argumentSectionName)`
`@@ -148,5 +147,22 @@ private static List<string> GetArgumentList(IConfigurationSection workerConfigSe`
`148`	`147`	`}`
`149`	`148`	`return null;`
`150`	`149`	`}`
	`150`	`+`
	`151`	`+ public ValidateOptionsResult Validate(string name, HttpWorkerOptions options)`
	`152`	`+ {`
	`153`	`+ if (options.IsPortManuallySet)`
	`154`	`+ {`
	`155`	`+ var port = options.Port;`
	`156`	`+`
	`157`	`+ if (port == 0 \|\| !WorkerUtilities.CanBindToPort(port))`
	`158`	`+ {`
	`159`	`+ throw new HostConfigurationException($"Unable to bind to port {port} specified in configuration. Please specify a different port or remove the section to allow dynamic binding of port.");`
	`160`	`+ }`
	`161`	`+`
	`162`	`+ _logger.LogInformation("Using port {port} specified via configuration for custom handler.", port);`
	`163`	`+ }`
	`164`	`+`
	`165`	`+ return ValidateOptionsResult.Success;`
	`166`	`+ }`
`151`	`167`	`}`
`152`	`168`	`}`