package openidea:plugin@1.3.0;

/// HTTP endpoints found in a project (`[[contributes.endpoints]]`).
interface endpoints-provider {
    use types.{error, location};
    use invocation.{invocation};

    /// One HTTP route.
    record endpoint {
        /// `none` accepts any HTTP method.
        method: option<string>,
        /// Path parameters use braces, e.g. `/photos/{id}`.
        path: string,
        /// Shown next to the route, e.g. `Rails`.
        framework: string,
        /// Display name, e.g. `PhotosController#show`.
        handler: option<string>,
        /// Where the route is declared, inside the project.
        location: location,
    }

    /// The project's routes, complete. Called when the IDE first needs them and
    /// again after a file matching `files` changes; cached in between. Runs in
    /// the background: it can't ask the user.
    endpoints: func(ctx: borrow<invocation>) -> result<list<endpoint>, error>;
}