Skip to content

Commit 1a32155

Browse files
carldebillycarldebilly
committed
Introduce DI support and customizable server options
- Added dependency injection extensions for `Server` registration. - Introduced `ServerOptions` for configurable server settings (port, hostname, bind address). - Refactored `Server` constructors to support `ServerOptions`. - Updated tests to validate DI and `ServerOptions` functionality. - Simplified namespace declarations with file-scoped syntax.
1 parent e58c3b5 commit 1a32155

19 files changed

Lines changed: 926 additions & 402 deletions

‎README.md‎

Lines changed: 192 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
# Yllibed HttpServer
2-
This is a versatile http server designed to be used in mobile/UWP applications.
2+
3+
This is a versatile http server designed to be used in mobile/UWP applications and any applications which need to expose a simple web server.
34

45
## Packages and NuGet Statistics
56

@@ -17,30 +18,171 @@ This is a versatile http server designed to be used in mobile/UWP applications.
1718

1819
2. Register a server in your app:
1920
```csharp
20-
var myServer = new Server(8080); // create a web server on port 8080
21-
myServer.RegisterHandler(new StaticHandler("/", "text/plain", "Hello, world!")); // register a handler for the root
22-
var (uri4, uri6) = myServer.Start(); // start the server and get the URIs
21+
var myServer = new Server(); // Uses dynamic port (recommended)
22+
myServer.RegisterHandler(new StaticHandler("/", "text/plain", "Hello, world!"));
23+
var (uri4, uri6) = myServer.Start(); // Get the actual URIs with assigned ports
24+
25+
Console.WriteLine($"Server running on: {uri4}");
26+
```
27+
28+
Or specify a fixed port:
29+
```csharp
30+
var myServer = new Server(8080); // Fixed port
31+
myServer.RegisterHandler(new StaticHandler("/", "text/plain", "Hello, world!"));
32+
var (uri4, uri6) = myServer.Start();
33+
```
34+
35+
Or with dependency injection and configuration:
36+
```csharp
37+
var services = new ServiceCollection();
38+
services.AddYllibedHttpServer(opts =>
39+
{
40+
opts.Port = 0; // Dynamic port (recommended)
41+
opts.Hostname4 = "127.0.0.1";
42+
opts.Hostname6 = "::1";
43+
});
44+
45+
var sp = services.BuildServiceProvider();
46+
var server = sp.GetRequiredService<Server>();
47+
server.RegisterHandler(new StaticHandler("/", "text/plain", "Hello, world!"));
48+
var (uri4, uri6) = server.Start();
2349
```
2450

2551
## What it is
2652
* Simple web server which can be extended using custom code
2753
* No dependencies on ASP.NET or other frameworks, self-contained
54+
* Supports dependency injection and configuration via `IOptions<ServerOptions>`
55+
* Configurable bind addresses and hostnames for IPv4/IPv6
2856

2957
## What it is not
3058
* This HTTP server is not designed for performance or high capacity
3159
* It's perfect for small applications, or small need, like to act as _return url_ for OAuth2 authentication using external browser.
3260

61+
## Common use cases
62+
* Return URL for OAuth2 authentication using external browser
63+
* Remote diagnostics/monitoring on your app
64+
* Building a headless Windows IoT app (for SSDP discovery or simply end-user configuration)
65+
* Any other use case where you need to expose a simple web server
66+
3367
## Limitations
3468
* There is no support for HTTP 2.0+ (yet) or WebSockets
3569
* There is no support for HTTPS (TLS)
3670

37-
## What you can do with it
38-
* Use it for building a headless Windows IoT app (for SSDP discovery or simply end-user configuration)
39-
* Use it for remote diagnostics/monitoring on your app
71+
## Configuration and Dependency Injection
72+
73+
The server can now be configured via a `ServerOptions` POCO. You can construct `Server` directly with a `ServerOptions` instance, or register it with Microsoft.Extensions.DependencyInjection using `IOptions<ServerOptions>`.
74+
75+
### ServerOptions Properties
76+
77+
* `Port` - Port number to listen to (0 = dynamic)
78+
* `BindAddress4` - IPv4 address to bind the listener to (defaults to `IPAddress.Any`)
79+
* `BindAddress6` - IPv6 address to bind the listener to (defaults to `IPAddress.IPv6Any`)
80+
* `Hostname4` - Hostname used to compose the public IPv4 URI (defaults to "127.0.0.1")
81+
* `Hostname6` - Hostname used to compose the public IPv6 URI (defaults to "::1")
82+
83+
### Dynamic Port Assignment (Recommended)
84+
85+
Using port `0` enables **dynamic port assignment**, which is the **recommended approach** for most applications:
86+
87+
**Key Advantages:**
88+
- **Zero port conflicts**: The operating system automatically assigns an available port
89+
- **Perfect for testing**: Multiple test instances can run simultaneously without conflicts
90+
- **Microservices architecture**: Each service gets its own unique port automatically
91+
- **Team collaboration**: No need to coordinate port assignments between developers
92+
- **CI/CD friendly**: Parallel builds and tests work seamlessly
93+
94+
**Best Practices with Dynamic Ports:**
95+
96+
```csharp
97+
// ✅ Recommended: Use dynamic ports (default behavior)
98+
var server = new Server(); // Port 0 by default
99+
server.RegisterHandler(new StaticHandler("/", "text/plain", "Hello!"));
100+
var (uri4, uri6) = server.Start();
101+
102+
// Capture the actual assigned port for logging or service discovery
103+
var actualPort = new Uri(uri4).Port;
104+
Console.WriteLine($"Server started on port: {actualPort}");
105+
Console.WriteLine($"Access your service at: {uri4}");
106+
107+
// For service registration with discovery systems
108+
await RegisterWithServiceDiscovery(uri4);
109+
```
110+
111+
**In production with Dependency Injection:**
112+
113+
```csharp
114+
services.AddYllibedHttpServer(); // Uses port 0 by default - no conflicts!
115+
116+
// Or be explicit for documentation purposes:
117+
services.AddYllibedHttpServer(opts =>
118+
{
119+
opts.Port = 0; // Dynamic port - recommended
120+
opts.BindAddress4 = IPAddress.Any; // Accept from all interfaces
121+
opts.Hostname4 = Environment.MachineName; // Use machine name in URIs
122+
});
123+
```
40124

41-
# Tips
125+
**When NOT to use dynamic ports:**
126+
- Public-facing web services requiring well-known ports (80, 443)
127+
- Legacy systems expecting fixed ports
128+
- Load balancer configurations requiring static endpoints
129+
- Development scenarios where you need predictable URLs
42130

43-
## Opening port on Windows 10 IoT (typically on a Raspberry Pi)
131+
### Basic Configuration Example
132+
133+
```csharp
134+
var serverOptions = new ServerOptions
135+
{
136+
Port = 5000,
137+
Hostname4 = "192.168.1.100", // Custom hostname for callbacks
138+
BindAddress4 = IPAddress.Any // Listen on all interfaces
139+
};
140+
141+
var server = new Server(serverOptions);
142+
server.Start();
143+
```
144+
145+
### Dependency Injection Example
146+
147+
The cleanest approach using extension methods:
148+
149+
```csharp
150+
var services = new ServiceCollection();
151+
services.AddYllibedHttpServer(opts =>
152+
{
153+
opts.Port = 5000;
154+
opts.Hostname4 = "127.0.0.1";
155+
opts.Hostname6 = "::1";
156+
opts.BindAddress4 = IPAddress.Parse("0.0.0.0");
157+
});
158+
159+
var sp = services.BuildServiceProvider();
160+
var server = sp.GetRequiredService<Server>();
161+
server.Start();
162+
```
163+
164+
Alternative using `services.Configure<>()` and automatic constructor selection:
165+
166+
```csharp
167+
var services = new ServiceCollection();
168+
services.Configure<ServerOptions>(opts =>
169+
{
170+
opts.Port = 5000;
171+
opts.Hostname4 = "127.0.0.1";
172+
opts.Hostname6 = "::1";
173+
});
174+
services.AddSingleton<Server>(); // Uses IOptions<ServerOptions> constructor automatically
175+
176+
var sp = services.BuildServiceProvider();
177+
var server = sp.GetRequiredService<Server>();
178+
server.Start();
179+
```
180+
181+
This allows you to control the bind addresses and hostnames used to compose the public URIs that the server logs, which is especially useful for OAuth callbacks and REST API applications.
182+
183+
## Tips
184+
185+
### Opening port on Windows 10 IoT (typically on a Raspberry Pi)
44186
If you want to open "any" port on a Raspberry Pi running Windows 10 IoT, you may
45187
need to open a port.
46188

@@ -52,3 +194,44 @@ need to open a port.
52194
```shell
53195
netsh advfirewall firewall add rule name="My Application Webserver" dir=in action=allow protocol=TCP localport=8080
54196
```
197+
198+
### OAuth2 Callback Configuration
199+
When using this server for OAuth2 callbacks, dynamic ports are especially useful:
200+
201+
```csharp
202+
services.AddYllibedHttpServer(); // Dynamic port prevents conflicts
203+
204+
var server = serviceProvider.GetRequiredService<Server>();
205+
server.RegisterHandler(new MyOAuthCallbackHandler());
206+
var (uri4, uri6) = server.Start();
207+
208+
// Use the actual URI for OAuth redirect registration
209+
var redirectUri = $"{uri4}/oauth/callback";
210+
Console.WriteLine($"Register this redirect URI with your OAuth provider: {redirectUri}");
211+
212+
// No port conflicts even if multiple OAuth flows run simultaneously!
213+
```
214+
215+
For scenarios requiring fixed callback URLs:
216+
```csharp
217+
services.Configure<ServerOptions>(opts =>
218+
{
219+
opts.Port = 5001;
220+
opts.Hostname4 = "127.0.0.1"; // Match your OAuth redirect URI
221+
opts.BindAddress4 = IPAddress.Loopback; // Only accept local connections
222+
});
223+
```
224+
225+
### Listening on All Interfaces
226+
To accept connections from other machines on your network:
227+
228+
```csharp
229+
var serverOptions = new ServerOptions
230+
{
231+
Port = 8080,
232+
BindAddress4 = IPAddress.Any, // Listen on all IPv4 interfaces
233+
BindAddress6 = IPAddress.IPv6Any, // Listen on all IPv6 interfaces
234+
Hostname4 = "192.168.1.100", // Your actual IP for public URIs
235+
Hostname6 = "::1" // IPv6 loopback
236+
};
237+
```

‎Yllibed.HttpServer.Json.Tests/FixtureBase.cs‎

Lines changed: 15 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -4,26 +4,22 @@
44
using System.Threading;
55
using Microsoft.VisualStudio.TestTools.UnitTesting;
66

7-
namespace Yllibed.HttpServer.Json.Tests
8-
{
9-
public class FixtureBase
10-
{
11-
protected CancellationToken CT;
12-
private CancellationTokenSource _ctSource;
7+
namespace Yllibed.HttpServer.Json.Tests;
138

14-
[TestInitialize]
15-
public void Initialize()
16-
{
17-
_ctSource = Debugger.IsAttached
18-
? new CancellationTokenSource()
19-
: new CancellationTokenSource(TimeSpan.FromSeconds(10));
20-
CT = _ctSource.Token;
21-
}
9+
public class FixtureBase
10+
{
11+
protected CancellationToken CT;
12+
private CancellationTokenSource _ctSource;
2213

23-
[TestCleanup]
24-
public void Terminate()
25-
{
26-
_ctSource.Dispose();
27-
}
14+
[TestInitialize]
15+
public void Initialize()
16+
{
17+
_ctSource = Debugger.IsAttached
18+
? new CancellationTokenSource()
19+
: new CancellationTokenSource(TimeSpan.FromSeconds(10));
20+
CT = _ctSource.Token;
2821
}
22+
23+
[TestCleanup]
24+
public void Terminate() => _ctSource.Dispose();
2925
}

‎Yllibed.HttpServer.Json.Tests/JsonHandlerBaseFixture.cs‎

Lines changed: 39 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -7,59 +7,63 @@
77
using FluentAssertions;
88
using Microsoft.VisualStudio.TestTools.UnitTesting;
99
using Newtonsoft.Json;
10+
using Yllibed.HttpServer.Json;
1011

11-
namespace Yllibed.HttpServer.Json.Tests
12+
namespace Yllibed.HttpServer.Json.Tests;
13+
14+
[TestClass]
15+
public class JsonHandlerBaseFixture : FixtureBase
1216
{
13-
[TestClass]
14-
public class JsonHandlerBaseFixture : FixtureBase
17+
[TestMethod]
18+
public async Task TestSimpleGet_WithJsonHandler()
1519
{
16-
[TestMethod]
17-
public async Task TestSimpleGet_WithJsonHandler()
18-
{
19-
var server = new Server();
20+
var server = new Server();
2021

21-
var (uri4, uri6) = server.Start();
22-
var requestUri = uri4 + "abcd?a=1&b=%20%2020";
22+
var (uri4, uri6) = server.Start();
23+
var requestUri = uri4 + "abcd?a=1&b=%20%2020";
2324

24-
var sut = new MyJsonHandler("GET", "abcd");
25+
var sut = new MyJsonHandler("GET", "abcd");
2526

26-
using (server.RegisterHandler(sut))
27+
using (server.RegisterHandler(sut))
28+
{
29+
using (var client = new HttpClient())
2730
{
28-
using (var client = new HttpClient())
29-
{
30-
var response = await client.GetAsync(requestUri, CT);
31-
response.StatusCode.Should().Be(HttpStatusCode.OK);
31+
var response = await client.GetAsync(requestUri, CT);
32+
response.StatusCode.Should().Be(HttpStatusCode.OK);
3233

33-
var result = JsonConvert.DeserializeObject<MyResultPayload>(await response.Content.ReadAsStringAsync(CT));
34-
result.Should().NotBeNull();
35-
result.Should().BeEquivalentTo(new { A = "1", B = " 20" });
36-
}
34+
var result = JsonConvert.DeserializeObject<MyResultPayload>(await response.Content.ReadAsStringAsync(CT).ConfigureAwait(false));
35+
result.Should().NotBeNull();
36+
result.Should().BeEquivalentTo(new { A = "1", B = " 20" });
3737
}
3838
}
39+
}
3940

40-
public class MyResultPayload
41+
public class MyResultPayload
42+
{
43+
public string? A { get; set; }
44+
public string? B { get; set; }
45+
}
46+
47+
private sealed class MyJsonHandler : JsonHandlerBase<MyResultPayload>
48+
{
49+
public MyJsonHandler(string method, string path) : base(method, path)
4150
{
42-
public string? A { get; set; }
43-
public string? B { get; set; }
4451
}
4552

46-
private sealed class MyJsonHandler(string method, string path) : JsonHandlerBase<MyResultPayload>(method, path)
53+
protected override async Task<(MyResultPayload result, ushort statusCode)> ProcessRequest(CancellationToken ct, string relativePath, IDictionary<string, string[]> queryParameters)
4754
{
48-
protected override async Task<(MyResultPayload result, ushort statusCode)> ProcessRequest(CancellationToken ct, string relativePath, IDictionary<string, string[]> queryParameters)
49-
{
50-
queryParameters.TryGetValue("a", out var a);
51-
queryParameters.TryGetValue("b", out var b);
55+
queryParameters.TryGetValue("a", out var a);
56+
queryParameters.TryGetValue("b", out var b);
5257

53-
await Task.Yield();
58+
await Task.Yield();
5459

55-
var result = new MyResultPayload
56-
{
57-
A = a?.FirstOrDefault(),
58-
B = b?.FirstOrDefault(),
59-
};
60+
var result = new MyResultPayload
61+
{
62+
A = a?.FirstOrDefault(),
63+
B = b?.FirstOrDefault(),
64+
};
6065

61-
return (result, 200);
62-
}
66+
return (result, 200);
6367
}
6468
}
6569
}

0 commit comments

Comments
 (0)