namespace NpgsqlRest

{

public interface IEndpointCreateHandler

{

/// <summary>

/// Before creating endpoints.

/// </summary>

/// <param name="builder">current application builder</param>

/// <param name="options">current NpgsqlRest options</param>

void Setup(IApplicationBuilder builder, NpgsqlRestOptions options) { }

/// <summary>

/// Called by the core comment parser, within its single parse pass, for each comment line

/// that core did NOT recognize as a built-in directive. Lets a plugin claim its own

/// annotations (e.g. <c>openapi …</c>, <c>mcp …</c>) without a second pass over the comment.

/// <para>

/// If this plugin owns the line, apply it (typically by storing into

/// <see cref="RoutineEndpoint.Items"/>) and return a <see cref="CommentLineResult"/> with a

/// short label — core logs it centrally (consistent with built-in annotation logging) and

/// stops offering the line to other handlers. Return <c>null</c> if the line is not this

/// plugin's annotation; it is then offered to the next handler, and finally surfaced via

/// <see cref="RoutineEndpoint.UnhandledCommentLines"/> (prose) if no handler claims it.

/// </para>

/// <paramref name="words"/> / <paramref name="wordsLower"/> are pre-tokenized by core (split

/// on space/comma; the lower-cased variant for keyword matching) so handlers do not re-tokenize.

/// <para>

/// Set <see cref="CommentLineResult.RequestsEndpoint"/> to true when the annotation means the

/// routine should be exposed as an endpoint (e.g. <c>mcp</c>) — under

/// <see cref="CommentsMode.OnlyAnnotated"/> this lets a routine with no HTTP tag still be

/// created. Leave it false for pure modifiers (e.g. <c>openapi hide</c>), which must NOT by

/// themselves cause an endpoint to be created.

/// </para>

/// </summary>

CommentLineResult? HandleCommentLine(RoutineEndpoint endpoint, string line, string[] words, string[] wordsLower) => null;

/// <summary>

/// Annotation keywords (first word of a comment line, lower-case, without the optional <c>@</c>

/// prefix) for which this handler's <see cref="HandleCommentLine"/> returns

/// <see cref="CommentLineResult.RequestsEndpoint"/> = true (e.g. <c>mcp</c>, <c>mcp_name</c>).

/// <para>

/// Used by endpoint sources that need a cheap, textual pre-check for exposure intent before the

/// comment parser runs — e.g. the SQL file source skips files with no HTTP tag, but a file whose

/// comment carries one of these keywords is an endpoint candidate (an MCP-only tool) and must

/// not be skipped. Default: empty (this handler never requests endpoints).

/// </para>

/// </summary>

string[] EndpointRequestingAnnotations => [];

/// <summary>

/// After successful endpoint creation.

/// </summary>

void Handle(RoutineEndpoint endpoint) { }

/// <summary>

/// After all endpoints are created.

/// </summary>

void Cleanup(RoutineEndpoint[] endpoints) { }

/// <summary>

/// After all endpoints are created.

/// </summary>

void Cleanup() { }

}

/// <summary>

/// Result of <see cref="IEndpointCreateHandler.HandleCommentLine"/> when a plugin claims a comment

/// line. <c>Label</c> is a short description logged centrally by core (consistent with built-in

/// annotation logging). <c>RequestsEndpoint</c> = true signals the routine should be created as an

/// endpoint even without an HTTP tag (exposure intent); false = modifier only.

/// </summary>

public readonly record struct CommentLineResult(string Label, bool RequestsEndpoint = false);

}