Skip to content

bruce48x/Lakona / skills/lakona-implement-http-service

lakona-implement-http-service

Verified

Implement or update complete Lakona Application HTTP services in Server.Hotfix. Use when adding an operations endpoint, webhook, payment callback, or other request/response route; changing LakonaHttpService or LakonaHttpEndpoint declarations; selecting listener exposure; fixing HTTP manifest-to-Hotfix binding; or validating raw-body, cancellation, idempotency, status, and response behavior.

FileKindSize
SKILL.mdskill md6.9 KB
agents/openai.yamlconfig357 B
references/http-service-shapes.mdmarkdown5.3 KB

references/http-service-shapes.md

View on GitHub
# Lakona Application HTTP Shapes

## Contents

- [Hotfix Service](#hotfix-service)
- [Reload Eligibility](#reload-eligibility)
- [Request And Response Surface](#request-and-response-surface)
- [Listener Exposure](#listener-exposure)
- [Signed And Retryable Requests](#signed-and-retryable-requests)

## Hotfix Service

Declare the route and implement the handler together in the Hotfix assembly.
The following is a declaration-only sketch, intentionally incomplete and not
deployable. Replace its body with the project's real verification and durable
acceptance path before building or exposing this route:

```csharp
using Lakona.Game.Server.Hotfix.Abstractions;
using Lakona.Game.Server.Http;

[LakonaHttpService("payment-webhooks")]
public sealed class PaymentWebhookService
{
    [LakonaHttpEndpoint("POST", "/payments/notify")]
    public ValueTask<LakonaHttpResponse> NotifyAsync(LakonaHttpCall call)
    {
        // Intentionally omitted: implement Signed And Retryable Requests below.
        // No success response is valid until that acceptance path completes.
    }
}
```

The generated validation requires a top-level public sealed non-generic class
and public instance handlers returning exactly
`ValueTask<LakonaHttpResponse>`. Constructor-inject concrete HotfixComponent
Store/Util dependencies for business operations. Stable infrastructure interfaces
(configuration, secret providers, third-party clients) remain valid; component
aliases, interfaces, factories, and overrides are unsupported.
Use `call.Actors` or `call.GameServer` only when the product behavior needs
them.

Application HTTP has no user-authored numeric method id. Service name, HTTP
method, and route pattern define protocol identity. The initial generation
freezes the process-local route manifest; adding, removing, or changing a route
requires a process restart. Route patterns under `/_lakona/**` belong to
Management HTTP.

## Reload Eligibility

A behavior-only change preserves the service name, HTTP method, and route
pattern. Handler method names, implementation logic, constructor dependencies,
and response behavior may change without changing the manifest, so the
candidate remains eligible for in-process Hotfix reload.

Adding or removing an endpoint, or changing its service name, HTTP method, or
route pattern, changes the manifest and requires a process restart. A response
schema change is not blocked by manifest validation, but it remains an external
protocol compatibility decision.

Do not work around the frozen manifest with application-owned dynamic endpoint
publication, a catch-all router, or relaxed validation. Preserve the current
framework boundary until Lakona adopts a generation-consistent dynamic routing
design.

## Request And Response Surface

`call.Request` is a bounded snapshot detached from ASP.NET and provides:

- `RawBody`
- `Headers`
- `Query`
- `RouteValues`
- `AuthenticatedName`
- `RemoteEndpoint`
- `TraceIdentifier`

The call also provides `CancellationToken`, `Services`, `Actors`, and
`GameServer`. Treat snapshot buffers and collections as request-owned,
read-only data.

Return `LakonaHttpResponse.Text(...)`, `LakonaHttpResponse.Json(...)`, or a
fully materialized `LakonaHttpResponse` when custom headers or bytes are
required. Product validation selects product status codes; framework admission
and hosting failures retain framework-owned mappings.

## Listener Exposure

Expose the service name on the intended physical listener:

```json
{
  "Lakona": {
    "Http": {
      "Listeners": [
        {
          "Id": "payments",
          "Host": "0.0.0.0",
          "Port": 21001,
          "Services": [ "payment-webhooks" ],
          "MaximumBodyBytes": 262144,
          "RequestTimeoutSeconds": 15
        }
      ]
    }
  }
}
```

Listener selection uses the accepted local socket. A listener exposes only its
configured services. Validate bind addresses and trusted-edge assumptions as
deployment policy rather than inferring security from names such as `internal`.

## Signed And Retryable Requests

For a signed webhook:

1. Read the signature and timestamp from the bounded headers.
2. Verify against `RawBody` before decoding or normalizing it.
3. Enforce the provider's replay window and secret-rotation policy.
4. Derive an idempotency key from a trusted provider event identifier.
5. Atomically record acceptance or route it to the authoritative actor/store.
6. Return success only at the durability level promised to the caller. Reject
   invalid signatures or replay-window violations before mutation; acknowledge
   a duplicate only after confirming its previously durable acceptance. A store
   failure must not fall through to a successful response.
7. Pass `call.CancellationToken` through every asynchronous dependency.

Keep provider-specific policy and business resource operations in Hotfix.
Inject their concrete HotfixComponent. Prefer its Hotfix
`[ComponentConfigureServices]` for stable root-DI client registration, or App
`[ComponentState]` for asynchronously acquired handles. App `AddServices` still
serves global host composition. Use the component Skill for first Start/final
Stop, role filtering, candidate cleanup and disposal; HTTP handlers do not own
cross-generation resource initialization. A stable infrastructure interface may
still provide secrets or a third-party client without moving business policy
into App.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall