(* Copyright (C) 2017--2025  Petter A. Urkedal <paurkedal@gmail.com>
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or (at your
 * option) any later version, with the LGPL-3.0 Linking Exception.
 *
 * This library is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * and the LGPL-3.0 Linking Exception along with this library.  If not, see
 * <http://www.gnu.org/licenses/> and <https://spdx.org>, respectively.
 *)

(** Request specification.

    A Caqti request is a function to generate a query string from information
    about the driver, along with type descriptors to encode parameters and
    decode rows returned from the same query.  Requests are passed to
    {!Caqti_connection_sig.S.call} or one of its shortcut methods provided by a
    database connection handle.

    The request often represent a prepared query, in which case it is static and
    can be defined directly in a module scope.  However, an optional [oneshot]
    parameter may be passed to indicate a dynamically generated query. *)

(** {2 Primitives} *)

type ('a, 'b, +'m) t = ('a, 'b, 'm) Caqti_template.Request.t
(** A request specification embedding a query generator, parameter encoder, and
    row decoder.
    - ['a] is the type of the expected parameter bundle.
    - ['b] is the type of a returned row.
    - ['m] is the possible multiplicities of returned rows. *)

val create :
  ?oneshot: bool ->
  'a Caqti_type.t -> 'b Caqti_type.t -> 'm Caqti_mult.t ->
  (Caqti_driver_info.t -> Caqti_query.t) -> ('a, 'b, 'm) t
(** [create arg_type row_type row_mult f] is a request which takes parameters of
    type [arg_type], returns rows of type [row_type] with multiplicity
    [row_mult], and which sends query strings generated from the query [f di],
    where [di] is the {!Caqti_driver_info.t} of the target driver.  The driver
    is responsible for turning parameter references into a form accepted by the
    database, while other differences must be handled by [f].

    @param oneshot
      Disables caching of a prepared statements on connections for this query.

        - If false (the default), the statement is prepared and a handle is
          permanently attached to the connection object right before the first
          time it is executed.

        - If true, everything allocated in order to execute the statement is
          released after use.

      In other words, the default is suitable for queries which are bound to
      static modules.  Conversely, you should pass [~oneshot:true] if the query
      is dynamically generated, whether it is within a function or a dynamic
      module, since there will otherwise be a memory leak associated with
      long-lived connections.  You might as well also pass [~oneshot:true] if
      you know that the query will only executed at most once (or a very few
      times) on each connection. *)

val param_type : ('a, _, _) t -> 'a Caqti_type.t
(** [param_type req] is the type of parameter bundles expected by [req]. *)

val row_type : (_, 'b, _) t -> 'b Caqti_type.t
(** [row_type req] is the type of rows returned by [req]. *)

val row_mult : (_, _, 'm) t -> 'm Caqti_mult.t
(** [row_mult req] indicates how many rows [req] may return.  This is asserted
    when constructing the query. *)

(**/**)
val query_id : ('a, 'b, 'm) t -> int option
[@@alert deprecated
  "This function is no longer used internally by Caqti and will be removed."]
(**/**)

val query : ('a, 'b, 'm) t -> Caqti_driver_info.t -> Caqti_query.t
(** [query req] is the function which generates the query of this request
    possibly tailored for the given driver. *)


(** {2 Convenience Interface} *)

module Infix : sig
  (** The following operators provides a more visually appealing way of
      expressing requests.  They are implemented in terms of {!create} and
      {!Caqti_query.of_string_exn}, meaning the the query string arguments
      accepts {{!query_template} The Syntax of Query Templates}.

      The [?oneshot] argument defaults to [false], so when not constructing
      one-shot queries, the full application [(pt -->! rt) f] can be written
      [pt -->! rt @@ f], which motivates the {!(@:-)} and {!(@@:-)} shortcuts.

      In the simplest case you can use this module directly together with
      {!Caqti_type}:
      {[
        let bounds_upto_req =
          let open Caqti_type.Std in
          let open Caqti_request.Infix in
          tup2 int32 float -->! option (tup2 float float) @:-
          "SELECT min(y), max(y) FROM samples WHERE series_id = ? AND x < ?"
      ]}
      For more complex applications it may be convenient to provide a custom
      module, to avoid the double open and to customize the operators, e.g.
      {[
        module Caqtireq = struct
          include Caqti_type.Std
          include Caqti_type_calendar (* if needed, link caqti-type-calendar *)
          include Caqti_request.Infix

          (* Any additional types. *)
          let password = redacted string
          let uri =
            custom ~encode:(fun x -> Ok (Uri.to_string x))
                   ~decode:(fun s -> Ok (Uri.of_string s)) string

          (* Optionally define a custom environment providing two schema names.
           * The references should only be assigned at startup. *)
          let myapp_schema = ref "myapp"
          let mylib_schema = ref "mylib"
          let env = function
           | "" -> Caqti_query.L !myapp_schema
           | "mylib" -> Caqti_query.L !mylib_schema
           | _ -> raise Not_found

          (* Since we have a custom environment, override the definitions of the
           * following operators to perform the substitution. *)
          let (@:-) t qs =
            let q = Caqti_query.expand env (Caqti_query.of_string_exn qs) in
            t (fun _ -> q)
          let (@@:-) t qsf =
            t (fun driver_info ->
              let qs = qsf (Caqti_driver_info.dialect_tag driver_info) in
              Caqti_query.expand env (Caqti_query.of_string_exn qs))
        end
      ]}
      If you don't like using global references, or you need to work with
      different enviroments for different connections, you should instead pass
      the environment function when connecting to the database.  We can now
      simplify and schema-qualify the previous request,
      {[
        let bounds_upto_req =
          let open Caqtireq in
          tup2 int32 float -->! option (tup2 float float) @:-
          "SELECT min(y), max(y) FROM $.samples WHERE series_id = ? AND x < ?"
      ]}
      {!section:indep} also provides alternative arrow operators for this common
      case, which allows using short-from local open,
      {[
        let bounds_upto_req =
          Caqtireq.(tup2 int32 float ->! option (tup2 float float))
          "SELECT min(y), max(y) FROM $.samples WHERE series_id = ? AND x < ?"
      ]}
   *)

  (** {2:indep Constructors for Driver-Independent Requests} *)

  val ( ->. ) :
    'a Caqti_type.t -> unit Caqti_type.t ->
    ?oneshot: bool -> string -> ('a, unit, [`Zero]) t
  (** [(pt ->. Caqti_type.unit) ?oneshot s] is the request which sends the
      query string [s], encodes parameters according to [pt], and expects no
      result rows. See {!create} for the meaning of [oneshot]. *)

  val ( ->! ) :
    'a Caqti_type.t -> 'b Caqti_type.t ->
    ?oneshot: bool -> string -> ('a, 'b, [`One]) t
  (** [(pt ->! rt) ?oneshot s] is the request which sends the query string [s],
      encodes parameters according to [pt], and decodes a single result row
      according to [rt]. See {!create} for the meaning of [oneshot]. *)

  val ( ->? ) :
    'a Caqti_type.t -> 'b Caqti_type.t ->
    ?oneshot: bool -> string -> ('a, 'b, [`Zero | `One]) t
  (** [(pt ->? rt) ?oneshot s] is the request which sends the query string [s],
      encodes parameters according to [pt], and decodes zero or one result row
      according to [rt]. See {!create} for the meaning of [oneshot]. *)

  val ( ->* ) :
    'a Caqti_type.t -> 'b Caqti_type.t ->
    ?oneshot: bool -> string -> ('a, 'b, [`Zero | `One | `Many]) t
  (** [(pt ->* rt) ?oneshot s] is the request which sends the query string [s],
      encodes parameters according to [pt], and decodes any number of result
      rows according to [rt]. See {!create} for the meaning of [oneshot]. *)

  (** {2 Constructors for Driver-Dependent Requests}

      The below arrow operators takes a function instead of a string as their
      third argument.  The function receives information about the current
      driver and returns a {!Caqti_query.t}.  This is the most general way of
      providing the query string.

      As an alternative to using plain application (or [@@]) for the third
      positional argument, additional application operators are provided for
      convenience. *)

  val ( -->. ) :
    'a Caqti_type.t -> unit Caqti_type.t ->
    ?oneshot: bool -> (Caqti_driver_info.t -> Caqti_query.t) ->
    ('a, unit, [`Zero]) t
  (** [(pt -->. Caqti_type.unit) ?oneshot f] is the request which sends the
      query string returned by [f], encodes parameters according to [pt], and
      expects no result rows. See {!create} for the meaning of [oneshot]. *)

  val ( -->! ) :
    'a Caqti_type.t -> 'b Caqti_type.t ->
    ?oneshot: bool -> (Caqti_driver_info.t -> Caqti_query.t) ->
    ('a, 'b, [`One]) t
  (** [(pt -->! rt) ?oneshot f] is the request which sends the query string
      returned by [f], encodes parameters according to [pt], and decodes a
      single result row according to [rt]. See {!create} for the meaning of
      [oneshot]. *)

  val ( -->? ) :
    'a Caqti_type.t -> 'b Caqti_type.t ->
    ?oneshot: bool -> (Caqti_driver_info.t -> Caqti_query.t) ->
    ('a, 'b, [`Zero | `One]) t
  (** [(pt -->? rt) ?oneshot f] is the request which sends the query string
      returned by [f], encodes parameters according to [pt], and decodes zero or
      one result row according to [rt]. See {!create} for the meaning of
      [oneshot]. *)

  val ( -->* ) :
    'a Caqti_type.t -> 'b Caqti_type.t ->
    ?oneshot: bool -> (Caqti_driver_info.t -> Caqti_query.t) ->
    ('a, 'b, [`Zero | `One | `Many]) t
  (** [(pt -->* rt) ?oneshot f] is the request which sends the query string
      returned by [f], encodes parameters according to [pt], and decodes any
      number of result rows according to [rt]. See {!create} for the meaning of
      [oneshot]. *)

  val ( @:- ) :
    ((Caqti_driver_info.t -> Caqti_query.t) -> ('a, 'b, 'm) t) ->
    string -> ('a, 'b, 'm) t
  (** Applies a dialect-independent query string which is parsed with
      {!Caqti_query.of_string_exn}.  Composition with arrow operators from this
      section, gives the corresponding operators from {!section:indep}. *)

  val ( @@:- ) :
    ((Caqti_driver_info.t -> Caqti_query.t) -> ('a, 'b, 'm) t) ->
    (Caqti_driver_info.dialect_tag -> string) -> ('a, 'b, 'm) t
  (** Applies a dialect-dependent query string which is parsed with
      {!Caqti_query.of_string_exn}. *)

end


(** {2 Printing} *)

val make_pp :
  ?env: (Caqti_driver_info.t -> string -> Caqti_query.t) ->
  ?driver_info: Caqti_driver_info.t ->
  unit -> Format.formatter -> ('a, 'b, 'm) t -> unit
(** [make_pp ?env ?driver_info ()] is a pretty-printer for a request, which
    expands the query using [env] and [driver_info].

    @param env
      Used to partially expand the query string.  Defaults to the empty
      environment.

    @param driver_info
      The driver info to pass to the call-back which returns the query.
      Defaults to {!Caqti_driver_info.dummy}. *)

val pp : Format.formatter -> ('a, 'b, 'm) t -> unit
(** [pp ppf req] prints [req] on [ppf] in a form suitable for human
    inspection. *)

val make_pp_with_param :
  ?env: (Caqti_driver_info.t -> string -> Caqti_query.t) ->
  ?driver_info: Caqti_driver_info.t ->
  unit -> Format.formatter -> ('a, 'b, 'm) t * 'a -> unit
(** [make_pp_with_param ?env ?driver_info ()] is a pretty-printer for a
    request and parameter pair.  See {!make_pp} for the optional arguments.
    This functions is meant for debugging; the output is neither guaranteed to
    be consistent across releases nor to contain a complete record of the data.
    Lost database records cannot be reconstructed from the logs.

    Due to concerns about exposure of sensitive data in debug logs, this
    function only prints the parameter values if [CAQTI_DEBUG_PARAM] is set to
    [true].  If you enable it for applications which do not consistenly annotate
    sensitive parameters with {!Caqti_type.redacted}, make sure your debug logs
    are well-secured. *)

(** {2 How to Dynamically Assemble Queries and Parameters}

    In some cases, queries are constructed dynamically, e.g. when translating an
    expression for searching a database into SQL.  In such cases the number of
    parameters and their types will typically vary, as well.  A helper like the
    following can be used to existentially pack the parameter types along with
    the corresponding parameter values to allow collecing them incrementally:
    {[
      module Dynparam = struct
        type t = Pack : 'a Caqti_type.t * 'a -> t
        let empty = Pack (Caqti_type.unit, ())
        let add t x (Pack (t', x')) = Pack (Caqti_type.tup2 t' t, (x', x))
      end
    ]}
    Now, given a [param : Dynparam.t] and a corresponding query string [qs], one
    can construct a request and execute it:
    {[
      let Dynparam.Pack (pt, pv) = param in
      let req = Caqti_request.exec ~oneshot:true pt qs in
      C.exec req pv
    ]}
    Note that dynamically constructed requests should have [~oneshot:true]
    unless they are memoized.  Also note that it is natural to use {!create} for
    dynamically constructed queries, since it accepts the easily composible
    {!Caqti_query.t} type instead of plain strings.

    This scheme can be specialized for particular use cases, including
    generation of fragments of the [query], which reduces the risk of wrongly
    matching up parameters with their uses in the query string.
    *)