package dev.coph.nextusweb.server.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Binds a controller method to a route using a custom or non-standard HTTP method. Whereas
 * {@link GET}, {@link POST} and the other verb annotations hard-code the verb, {@code @CUSTOM}
 * lets the caller name the verb explicitly via {@link #method()} (for example {@code "HEAD"},
 * {@code "OPTIONS"} or a WebDAV-style verb).
 *
 * <p>The annotated method must have the signature {@code void handler(Request, Response)},
 * which the {@link AnnotationScanner} verifies during registration. The route path given by
 * {@link #value()} is combined with any {@link Controller#value() controller prefix}.</p>
 *
 * <p>Retained at {@link RetentionPolicy#RUNTIME runtime} for reflective scanning and only
 * applicable to {@link ElementType#METHOD methods}.</p>
 *
 * @see Route
 * @see AnnotationScanner
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface CUSTOM {

    /**
     * The HTTP method name this route responds to. Must be a value accepted by
     * {@link io.netty.handler.codec.http.HttpMethod#valueOf(String)}.
     *
     * @return the HTTP method name
     */
    String method();

    /**
     * The path this route is mounted at, relative to any controller prefix. Supports
     * {@code {param}} path parameters and {@code *} wildcards.
     *
     * @return the route path
     */
    String value();
}