diff --git a/AGENTS.md b/AGENTS.md index e39252f26..a93d95786 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,7 +22,7 @@ dotnet test Testing/Acceptance/GenHTTP.Testing.Acceptance.csproj -f net11.0 \ # Only one engine (Internal | Kestrel | Ioxide) TEST_ENGINE=Internal dotnet test Testing/Acceptance/GenHTTP.Testing.Acceptance.csproj -f net11.0 -cd Playground && dotnet run # sample server on http://localhost:8080 +cd Playground && dotnet run # minimal app on http://localhost:8080 ``` - Filter with `FullyQualifiedName~...`. `ClassName=Foo` silently matches nothing. @@ -49,7 +49,7 @@ cd Playground && dotnet run # sample server on ht | `Testing/Acceptance` | The test suite. Folder structure mirrors `API/`, `Engine/`, `Modules/`, `Adapters/`. | | `Benchmarks/` | BenchmarkDotNet micro-benchmarks. | | `Packages/` | Meta-package `.nuspec` files (`GenHTTP.Core`, `GenHTTP.Full`, and per-engine variants). | -| `Playground/` | Runnable samples for manual checks and for users to understand the API. | +| `Playground/` | A minimal app for manual checks. The samples for users are on the website (genhttp.org/samples). | The parser (Glyph11) and ioxide are separate projects consumed as NuGet packages. If they are checked out next to this repository (`../Glyph11`, `../ioxide`), read their source rather than guessing. Flag diff --git a/Playground/Program.cs b/Playground/Program.cs index 8ff2060cb..7ab508e1f 100644 --- a/Playground/Program.cs +++ b/Playground/Program.cs @@ -1,13 +1,12 @@ using GenHTTP.Engine.Internal; +using GenHTTP.Modules.IO; using GenHTTP.Modules.Practices; -using GenHTTP.Playground.Samples; - -var sample = LayoutingSample.Create(); +var app = Content.From(Resource.FromString("Hello World!")); return await Host.Create() - .Handler(sample) + .Handler(app) .Development() .Defaults() .RunAsync(); diff --git a/Playground/README.md b/Playground/README.md index 2f6dfdfe6..91245ffd9 100644 --- a/Playground/README.md +++ b/Playground/README.md @@ -1,15 +1,19 @@ # GenHTTP Playground -The playground provides code samples for quick reference and allows developers to -quickly validate things. - -| Sample | Description | -|----------------------------------------------------------------------|----------------------------------------------------------------------------------| -| [Layouting](./Samples/LayoutingSample.cs) | Allows an app to use multiple handlers by adding routing. | -| [Webservices](./Samples/WebserviceSample.cs) | Implements a REST webservice via a handler class. | -| [Functional](./Samples/FunctionalSample.cs) | Uses delegates to implement a web service (similar to ASP.NET Core Minimal API). | -| [Controllers](./Samples/ControllerSample.cs) | Uses controllers to implement a web service (similar to ASP.NET Core MVC). | -| [MCP Tools](./Samples/McpSample.cs) | Provides tools to AI agents such as Claude via the Model Context Protocol. | -| [Static Files](./Samples/StaticFileSample.cs) | Serves static files from a directory. | -| [Static Websites](./Samples/StaticWebsiteSample.cs) | Hosts a static website (with `index.html` support). | -| [Single Page Applications](./Samples/SinglePageApplicationSample.cs) | Hosts a SPA such as a React or Angular application. | +The playground is a minimal app to quickly try things out while working on GenHTTP. +Change the handler in [Program.cs](./Program.cs) as needed and start the server: + +```bash +cd Playground +dotnet run +``` + +The app is then served at http://localhost:8080/. + +## Samples + +Samples for the frameworks, handlers and concerns of GenHTTP can be found +[on the website](https://genhttp.org/samples/), where you can read their code and +send requests to them as they run live. + +The [Ioxide](./Samples/Ioxide/README.md) folder contains samples for the io_uring based engine. diff --git a/Playground/Samples/ControllerSample.cs b/Playground/Samples/ControllerSample.cs deleted file mode 100644 index e24a2ef25..000000000 --- a/Playground/Samples/ControllerSample.cs +++ /dev/null @@ -1,62 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.Controllers; -using GenHTTP.Modules.Layouting; -using GenHTTP.Modules.Reflection; - -namespace GenHTTP.Playground.Samples; - -public static class ControllerSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Shows how to declare and register a controller that will be invoked - * to handle incoming HTTP requests. - * - * See https://genhttp.org/documentation/content/frameworks/controllers/ - * - */ - - return Layout.Create() - .AddController("books"); - } - - public record Book(int Id, string Title); - - public class BookController - { - private static readonly List Books = - [ - new(1, "Lord of the Rings") - ]; - - // GET http://localhost:8080/books/ - [ControllerAction] - public List Index() => Books; - - // PUT http://localhost:8080/books/create with JSON/XML/... payload - [ControllerAction(Method.Put)] - public Book Create(Book book) - { - var toAdd = book with - { - Id = Books.Max(b => b.Id) + 1 - }; - - Books.Add(toAdd); - return toAdd; - } - - // DELETE http://localhost:8080/books/delete/1 - [ControllerAction(Method.Delete)] - public void Delete([FromPath] int id) - { - Books.RemoveAll(b => b.Id == id); - } - - } - -} diff --git a/Playground/Samples/CustomFrameworkSample.cs b/Playground/Samples/CustomFrameworkSample.cs deleted file mode 100644 index 992af6c1e..000000000 --- a/Playground/Samples/CustomFrameworkSample.cs +++ /dev/null @@ -1,81 +0,0 @@ -using GenHTTP.Api.Content; -using GenHTTP.Api.Infrastructure; -using GenHTTP.Api.Protocol; - -using GenHTTP.Modules.ApiBrowsing; -using GenHTTP.Modules.Conversion; -using GenHTTP.Modules.Functional.Provider; -using GenHTTP.Modules.Layouting; -using GenHTTP.Modules.OpenApi; -using GenHTTP.Modules.Reflection; -using GenHTTP.Modules.Reflection.Operations; - -namespace GenHTTP.Playground.Samples; - -public static class CustomFrameworkSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Shows how to implement a custom framework. - * - * See https://genhttp.org/documentation/content/frameworks/custom/ - * - */ - - return Layout.Create() - .Add(new CustomFrameworkHandler()) - .AddOpenApi() - .AddScalar(); - } - - public class CustomFrameworkHandler : IHandler, IServiceMethodProvider - { - private MethodCollection? _methods; - - public MethodCollection Methods => _methods ?? throw new InvalidOperationException("Handler is not prepared yet"); - - public async ValueTask PrepareAsync(IServer server) - { - var list = new List(); - - // specify the supported methods of the operation we are exposing - var supportedMethods = new MethodConfiguration([RequestMethod.Get]); - - // the actual piece of code to be executed - either a method info or a delegate - var methodInfo = GetType().GetMethod("ExposedMethod")!; - - // auto enables code generation, otherwise reflection only - var executionSettings = new ExecutionSettings(ExecutionMode.Auto); - - // configures the behavior for serialization, injection and formatting - var registry = new MethodRegistry( - Serialization.Default().Build(), - Injection.Default().Build(), - Formatting.Default().Build() - ); - - // build the operation we would like to provide - var operation = OperationBuilder.Create(server, ":id", methodInfo, null, executionSettings, supportedMethods, registry); - - // create a method handler from the operation which will serve it as an HTTP endpoint - // this handler requires an instance provider which tells the framework on which - // object to invoke the given method info or delegate - list.Add(new MethodHandler(operation, (_) => new(this), registry)); - - // build a method collection handler from all collected operations - // this handler is responsible for routing - _methods = new MethodCollection(list); - - await _methods.PrepareAsync(server); - } - - public ValueTask HandleAsync(IRequest request) => Methods.HandleAsync(request); - - public string ExposedMethod(int id) => id.ToString(); - - } - -} diff --git a/Playground/Samples/FunctionalSample.cs b/Playground/Samples/FunctionalSample.cs deleted file mode 100644 index f4f6463c4..000000000 --- a/Playground/Samples/FunctionalSample.cs +++ /dev/null @@ -1,47 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.Functional; -using GenHTTP.Modules.Layouting; - -namespace GenHTTP.Playground.Samples; - -public static class FunctionalSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Shows how to use delegates that will be invoked - * to handle incoming HTTP requests. - * - * See https://genhttp.org/documentation/content/frameworks/functional/ - * - */ - - var books = new List() - { - new(1, "Lord of the Rings") - }; - - var service = Inline.Create() - .Get(() => books) // GET http://localhost:8080/books/ - .Put((Book book) => // PUT http://localhost:8080/books/ with JSON/XML/... payload - { - var toAdd = book with - { - Id = books.Max(b => b.Id) + 1 - }; - - books.Add(toAdd); - return toAdd; - }) - .Delete(":id", (int id) => books.RemoveAll(b => b.Id == id)); // DELETE http://localhost:8080/books/1 - - return Layout.Create() - .Add("books", service); - } - - public record Book(int Id, string Title); - -} diff --git a/Playground/Samples/LayoutingSample.cs b/Playground/Samples/LayoutingSample.cs deleted file mode 100644 index dd03f9c3e..000000000 --- a/Playground/Samples/LayoutingSample.cs +++ /dev/null @@ -1,38 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.Files; -using GenHTTP.Modules.Functional; -using GenHTTP.Modules.Layouting; - -namespace GenHTTP.Playground.Samples; - -public static class LayoutingSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Layouts allow you to structure your web application and divide it into - * different logical parts. The layout will route incoming requests to the designated - * handler. Layouts can be nested as needed. - * - * See https://genhttp.org/documentation/content/handlers/layouting/ - * - */ - - // serve static files from the current directory - var assets = Assets.From("./"); - - // define a simple REST API - var api = Inline.Create() - .Get(() => "Hello World!"); - - // assemble our application from the parts above and - // register them at the given URLs - return Layout.Create() - .Add("assets", assets) // e.g. GET http://localhost:8080/assets/GenHTTP.Playground.xml - .Add("api", api); // e.g. GET http://localhost:8080/api/ - } - -} diff --git a/Playground/Samples/McpSample.cs b/Playground/Samples/McpSample.cs deleted file mode 100644 index cf57b28e5..000000000 --- a/Playground/Samples/McpSample.cs +++ /dev/null @@ -1,78 +0,0 @@ -using System.ComponentModel.DataAnnotations; - -using GenHTTP.Api.Content; -using GenHTTP.Api.Content.Documentation; -using GenHTTP.Api.Protocol; - -using GenHTTP.Modules.Layouting; -using GenHTTP.Modules.Mcp; - -namespace GenHTTP.Playground.Samples; - -public static class McpSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Shows how to provide tools to AI agents such as Claude via the - * Model Context Protocol (MCP). - * - * Add the endpoint to Claude Code via - * - * claude mcp add --transport http library http://localhost:8080/mcp - * - * and ask, for example, "Which books about Rome are in the library?". - * - * See https://genhttp.org/documentation/content/frameworks/mcp/ - * - */ - - var tools = Tools.Create() - .Server("library", "1.0.0", "Library") - .Instructions("Search for books before lending them to a reader.") - .Add() - .Add("get_time", "Returns the current time of the library (UTC)", [Tool(ReadOnly = true)] () => DateTime.UtcNow); - - return Layout.Create() - .Add("mcp", tools); - } - - public record Book(int Id, string Title, string? LentTo); - - public class LibraryTools - { - private static readonly List Books = - [ - new(1, "SPQR: A History of Ancient Rome", null), - new(2, "The Lord of the Rings", null) - ]; - - [Tool(ReadOnly = true)] - [Summary("Searches the books of the library by title")] - public List FindBooks([Summary("Part of the title, e.g. 'Rome'")] string query, [Range(1, 50)] int limit = 10) - => Books.Where(b => b.Title.Contains(query, StringComparison.OrdinalIgnoreCase)).Take(limit).ToList(); - - [Tool(Destructive = false)] - [Summary("Lends a book to a reader")] - public Book LendBook([Summary("The id of the book, as returned by find_books")] int bookId, [Summary("The name of the reader")] string reader) - { - var book = Books.FirstOrDefault(b => b.Id == bookId) - ?? throw new ProviderException(ResponseStatus.NotFound, $"There is no book with id {bookId}."); - - if (book.LentTo != null) - { - throw new ProviderException(ResponseStatus.Conflict, $"'{book.Title}' is already lent to {book.LentTo}."); - } - - var lent = book with { LentTo = reader }; - - Books[Books.IndexOf(book)] = lent; - - return lent; - } - - } - -} diff --git a/Playground/Samples/SinglePageApplicationSample.cs b/Playground/Samples/SinglePageApplicationSample.cs deleted file mode 100644 index e0163ca48..000000000 --- a/Playground/Samples/SinglePageApplicationSample.cs +++ /dev/null @@ -1,27 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.IO; -using GenHTTP.Modules.SinglePageApplications; - -namespace GenHTTP.Playground.Samples; - -public static class SinglePageApplicationSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Serves a single page application (SPA) from a directory (or resource tree in general). - * - * See https://genhttp.org/documentation/content/frameworks/single-page-applications/ - * - */ - - var files = ResourceTree.FromDirectory("/var/app"); - - return SinglePageApplication.From(files); - } - -} - diff --git a/Playground/Samples/StaticFileSample.cs b/Playground/Samples/StaticFileSample.cs deleted file mode 100644 index 2e30d43e6..000000000 --- a/Playground/Samples/StaticFileSample.cs +++ /dev/null @@ -1,24 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.Files; - -namespace GenHTTP.Playground.Samples; - -public static class StaticFileSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Serves files from a given directory or resource tree. - * - * See https://genhttp.org/documentation/content/handlers/static-content/ - * - */ - - // e.g. GET http://localhost:8080/assets/GenHTTP.Playground.xml - return Assets.From("./"); - } - -} diff --git a/Playground/Samples/StaticWebsiteSample.cs b/Playground/Samples/StaticWebsiteSample.cs deleted file mode 100644 index 7b2f88a5a..000000000 --- a/Playground/Samples/StaticWebsiteSample.cs +++ /dev/null @@ -1,27 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.IO; -using GenHTTP.Modules.StaticWebsites; - -namespace GenHTTP.Playground.Samples; - -public static class StaticWebsiteSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Serves a static website from a directory (or resource tree in general). - * - * See https://genhttp.org/documentation/content/frameworks/static-websites/ - * - */ - - var files = ResourceTree.FromDirectory("/var/www"); - - return StaticWebsite.From(files); - } - -} - diff --git a/Playground/Samples/WebserviceSample.cs b/Playground/Samples/WebserviceSample.cs deleted file mode 100644 index 613824142..000000000 --- a/Playground/Samples/WebserviceSample.cs +++ /dev/null @@ -1,64 +0,0 @@ -using GenHTTP.Api.Content; - -using GenHTTP.Modules.Controllers; -using GenHTTP.Modules.Layouting; -using GenHTTP.Modules.Reflection; -using GenHTTP.Modules.Webservices; - -namespace GenHTTP.Playground.Samples; - -public static class WebserviceSample -{ - - public static IHandlerBuilder Create() - { - /* - * - * Shows how to declare and register a class that will be invoked - * to handle incoming HTTP requests. - * - * See https://genhttp.org/documentation/content/frameworks/webservices/ - * - */ - - return Layout.Create() - .AddService("books"); - } - - public record Book(int Id, string Title); - - public class BookService - { - private static readonly List Books = - [ - new(1, "Lord of the Rings") - ]; - - // GET http://localhost:8080/books/ - [ResourceMethod] - public List List() => Books; - - // PUT http://localhost:8080/books/ with JSON/XML/... payload - [ResourceMethod(Method.Put)] - public Book Create(Book book) - { - var toAdd = book with - { - Id = Books.Max(b => b.Id) + 1 - }; - - Books.Add(toAdd); - - return toAdd; - } - - // DELETE http://localhost:8080/books/1 - [ResourceMethod(Method.Delete, ":id")] - public void Delete([FromPath] int id) - { - Books.RemoveAll(b => b.Id == id); - } - - } - -} diff --git a/README.md b/README.md index 78f17de85..d6041bda8 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,12 @@ Running this snippet will provide the following endpoints: ## Samples -The [playground](./Playground/) project provides a quick starting point to view sample code and find more complex apps -built with GenHTTP. See [the documentation](https://genhttp.org/documentation/content/) for all available capabilities. +The [samples](https://genhttp.org/samples/) on the website show the frameworks, handlers and concerns of GenHTTP as +complete programs, and let you send requests to them as they run live. See [the documentation](https://genhttp.org/documentation/content/) for all available capabilities. + +## Agentic Coding + +GenHTTP’s modules are decoupled and wired together explicitly, with no hidden magic, so every part of an application can be understood by reading its code. This makes GenHTTP a strong fit for agentic coding in C#, where AI agents can reliably understand, change and extend projects without unexpected side effects. ## Engines