diff --git a/Furniture.Bff.slnx b/Furniture.Bff.slnx new file mode 100644 index 0000000..ecda2bd --- /dev/null +++ b/Furniture.Bff.slnx @@ -0,0 +1,10 @@ + + + + + + + + + + diff --git a/docs/api/external-api-surface.md b/docs/api/external-api-surface.md new file mode 100644 index 0000000..b0b5433 --- /dev/null +++ b/docs/api/external-api-surface.md @@ -0,0 +1,15 @@ +# External API Surface + +## Active External Protocol + +- REST is the active external protocol for this BFF deployment. + +## Endpoint Baseline + +- `GET /api/furniture/{furnitureId}/availability` + +## Edge Responsibilities + +- Validate and normalize consumer request inputs. +- Map downstream service responses to consumer-facing shapes. +- Map downstream errors to consistent API error models. diff --git a/docs/architecture/protocol-adaptation.puml b/docs/architecture/protocol-adaptation.puml new file mode 100644 index 0000000..7d2790b --- /dev/null +++ b/docs/architecture/protocol-adaptation.puml @@ -0,0 +1,20 @@ +@startuml +skinparam packageStyle rectangle + +package "furniture-bff" { + class Program + interface IGetFurnitureAvailabilityHandler + class GetFurnitureAvailabilityHandler + interface IFurnitureServiceClient + + GetFurnitureAvailabilityHandler ..|> IGetFurnitureAvailabilityHandler + GetFurnitureAvailabilityHandler --> IFurnitureServiceClient +} + +package "Consumers" as Consumers +package "furniture-service" as FurnitureService + +Consumers --> Program : REST +Program --> IGetFurnitureAvailabilityHandler +IFurnitureServiceClient ..> FurnitureService : gRPC/internal +@enduml diff --git a/docs/operations/tracing-and-headers.md b/docs/operations/tracing-and-headers.md new file mode 100644 index 0000000..b159fa0 --- /dev/null +++ b/docs/operations/tracing-and-headers.md @@ -0,0 +1,16 @@ +# Tracing and Headers + +## Required Incoming Headers + +- `X-Correlation-Id` +- `X-Request-Id` + +## Forwarding Rules + +- Preserve correlation headers to downstream service calls. +- Add correlation headers if missing at the edge. + +## Observability Baseline + +- Log protocol, route, and correlation identifiers per request. +- Capture downstream call duration per request. diff --git a/src/Furniture.Bff.Application/Adapters/IFurnitureServiceClient.cs b/src/Furniture.Bff.Application/Adapters/IFurnitureServiceClient.cs new file mode 100644 index 0000000..1e118a1 --- /dev/null +++ b/src/Furniture.Bff.Application/Adapters/IFurnitureServiceClient.cs @@ -0,0 +1,16 @@ +using Furniture.Bff.Contracts.Api; + +namespace Furniture.Bff.Application.Adapters; + +/// +/// Service adapter boundary used by BFF handlers. +/// +public interface IFurnitureServiceClient +{ + /// + /// Retrieves furniture availability from downstream service. + /// + /// Furniture identifier. + /// Consumer-ready availability contract. + Task GetAvailabilityAsync(string furnitureId); +} diff --git a/src/Furniture.Bff.Application/Furniture.Bff.Application.csproj b/src/Furniture.Bff.Application/Furniture.Bff.Application.csproj new file mode 100644 index 0000000..c75bc4d --- /dev/null +++ b/src/Furniture.Bff.Application/Furniture.Bff.Application.csproj @@ -0,0 +1,10 @@ + + + net10.0 + enable + enable + + + + + diff --git a/src/Furniture.Bff.Application/Handlers/GetFurnitureAvailabilityHandler.cs b/src/Furniture.Bff.Application/Handlers/GetFurnitureAvailabilityHandler.cs new file mode 100644 index 0000000..7781661 --- /dev/null +++ b/src/Furniture.Bff.Application/Handlers/GetFurnitureAvailabilityHandler.cs @@ -0,0 +1,17 @@ +using Furniture.Bff.Application.Adapters; +using Furniture.Bff.Contracts.Api; + +namespace Furniture.Bff.Application.Handlers; + +/// +/// Default edge handler implementation for furniture availability. +/// +public sealed class GetFurnitureAvailabilityHandler(IFurnitureServiceClient serviceClient) + : IGetFurnitureAvailabilityHandler +{ + /// + public Task HandleAsync(GetFurnitureAvailabilityApiRequest request) + { + return serviceClient.GetAvailabilityAsync(request.FurnitureId); + } +} diff --git a/src/Furniture.Bff.Application/Handlers/IGetFurnitureAvailabilityHandler.cs b/src/Furniture.Bff.Application/Handlers/IGetFurnitureAvailabilityHandler.cs new file mode 100644 index 0000000..bcd5276 --- /dev/null +++ b/src/Furniture.Bff.Application/Handlers/IGetFurnitureAvailabilityHandler.cs @@ -0,0 +1,16 @@ +using Furniture.Bff.Contracts.Api; + +namespace Furniture.Bff.Application.Handlers; + +/// +/// Edge handler boundary for furniture availability endpoint. +/// +public interface IGetFurnitureAvailabilityHandler +{ + /// + /// Handles external request and returns API response. + /// + /// API request contract. + /// API response contract. + Task HandleAsync(GetFurnitureAvailabilityApiRequest request); +} diff --git a/src/Furniture.Bff.Contracts/Api/GetFurnitureAvailabilityApiRequest.cs b/src/Furniture.Bff.Contracts/Api/GetFurnitureAvailabilityApiRequest.cs new file mode 100644 index 0000000..42b9d38 --- /dev/null +++ b/src/Furniture.Bff.Contracts/Api/GetFurnitureAvailabilityApiRequest.cs @@ -0,0 +1,7 @@ +namespace Furniture.Bff.Contracts.Api; + +/// +/// External REST request contract for furniture availability. +/// +/// Furniture identifier provided by consumers. +public sealed record GetFurnitureAvailabilityApiRequest(string FurnitureId); diff --git a/src/Furniture.Bff.Contracts/Api/GetFurnitureAvailabilityApiResponse.cs b/src/Furniture.Bff.Contracts/Api/GetFurnitureAvailabilityApiResponse.cs new file mode 100644 index 0000000..c6068c8 --- /dev/null +++ b/src/Furniture.Bff.Contracts/Api/GetFurnitureAvailabilityApiResponse.cs @@ -0,0 +1,8 @@ +namespace Furniture.Bff.Contracts.Api; + +/// +/// External REST response contract for furniture availability. +/// +/// Requested furniture identifier. +/// Availability value for client display. +public sealed record GetFurnitureAvailabilityApiResponse(string FurnitureId, int QuantityAvailable); diff --git a/src/Furniture.Bff.Contracts/Furniture.Bff.Contracts.csproj b/src/Furniture.Bff.Contracts/Furniture.Bff.Contracts.csproj new file mode 100644 index 0000000..6c3a887 --- /dev/null +++ b/src/Furniture.Bff.Contracts/Furniture.Bff.Contracts.csproj @@ -0,0 +1,7 @@ + + + net10.0 + enable + enable + + diff --git a/src/Furniture.Bff.Rest/Endpoints/EndpointConventions.cs b/src/Furniture.Bff.Rest/Endpoints/EndpointConventions.cs new file mode 100644 index 0000000..d1cccb2 --- /dev/null +++ b/src/Furniture.Bff.Rest/Endpoints/EndpointConventions.cs @@ -0,0 +1,12 @@ +namespace Furniture.Bff.Rest.Endpoints; + +/// +/// Defines endpoint conventions for the furniture BFF REST surface. +/// +public static class EndpointConventions +{ + /// + /// Prefix used by public furniture API routes. + /// + public const string ApiPrefix = "/api/furniture"; +} diff --git a/src/Furniture.Bff.Rest/Furniture.Bff.Rest.csproj b/src/Furniture.Bff.Rest/Furniture.Bff.Rest.csproj new file mode 100644 index 0000000..2c53814 --- /dev/null +++ b/src/Furniture.Bff.Rest/Furniture.Bff.Rest.csproj @@ -0,0 +1,11 @@ + + + net10.0 + enable + enable + + + + + + diff --git a/src/Furniture.Bff.Rest/Program.cs b/src/Furniture.Bff.Rest/Program.cs new file mode 100644 index 0000000..aaac95c --- /dev/null +++ b/src/Furniture.Bff.Rest/Program.cs @@ -0,0 +1,13 @@ +using Furniture.Bff.Contracts.Api; + +var builder = WebApplication.CreateBuilder(args); + +// Stage 3 skeleton: single active external protocol for this deployment is REST. +var app = builder.Build(); + +app.MapGet("/api/furniture/{furnitureId}/availability", (string furnitureId) => +{ + return Results.Ok(new GetFurnitureAvailabilityApiResponse(furnitureId, 0)); +}); + +app.Run(); diff --git a/tests/Furniture.Bff.Application.UnitTests/Furniture.Bff.Application.UnitTests.csproj b/tests/Furniture.Bff.Application.UnitTests/Furniture.Bff.Application.UnitTests.csproj new file mode 100644 index 0000000..369c362 --- /dev/null +++ b/tests/Furniture.Bff.Application.UnitTests/Furniture.Bff.Application.UnitTests.csproj @@ -0,0 +1,21 @@ + + + net10.0 + enable + enable + false + + + + + + + + + + + + + + + diff --git a/tests/Furniture.Bff.Application.UnitTests/GetFurnitureAvailabilityHandlerTests.cs b/tests/Furniture.Bff.Application.UnitTests/GetFurnitureAvailabilityHandlerTests.cs new file mode 100644 index 0000000..8eabf74 --- /dev/null +++ b/tests/Furniture.Bff.Application.UnitTests/GetFurnitureAvailabilityHandlerTests.cs @@ -0,0 +1,27 @@ +using Furniture.Bff.Application.Adapters; +using Furniture.Bff.Application.Handlers; +using Furniture.Bff.Contracts.Api; + +namespace Furniture.Bff.Application.UnitTests; + +public class GetFurnitureAvailabilityHandlerTests +{ + [Fact] + public async Task HandleAsync_WhenCalled_DelegatesToServiceClient() + { + var handler = new GetFurnitureAvailabilityHandler(new FakeFurnitureServiceClient()); + + var response = await handler.HandleAsync(new GetFurnitureAvailabilityApiRequest("FUR-001")); + + Assert.Equal("FUR-001", response.FurnitureId); + Assert.Equal(3, response.QuantityAvailable); + } + + private sealed class FakeFurnitureServiceClient : IFurnitureServiceClient + { + public Task GetAvailabilityAsync(string furnitureId) + { + return Task.FromResult(new GetFurnitureAvailabilityApiResponse(furnitureId, 3)); + } + } +}