1/*  Part of SWISH
    2
    3    Author:        Jan Wielemaker
    4    E-mail:        jan@swi-prolog.org
    5    WWW:           http://www.swi-prolog.org
    6    Copyright (C): 2024, SWI-Prolog Solutions b.v.
    7    All rights reserved.
    8
    9    Redistribution and use in source and binary forms, with or without
   10    modification, are permitted provided that the following conditions
   11    are met:
   12
   13    1. Redistributions of source code must retain the above copyright
   14       notice, this list of conditions and the following disclaimer.
   15
   16    2. Redistributions in binary form must reproduce the above copyright
   17       notice, this list of conditions and the following disclaimer in
   18       the documentation and/or other materials provided with the
   19       distribution.
   20
   21    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
   22    "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
   23    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
   24    FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
   25    COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
   26    INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
   27    BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
   28    LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
   29    CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   30    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
   31    ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
   32    POSSIBILITY OF SUCH DAMAGE.
   33*/
   34
   35:- module(elastic,
   36          [ es_get/2,                   % +Path, -JSON
   37            es_put/2,
   38            es_post/2,                  % +Path, +Data
   39            es_post/3,                  % +Path, +Data, -Result
   40            es_create_index/2,
   41            es_delete_index/1,
   42            es_add/4,                   % +Index, +Doc, -Reply, +Options
   43            es_search/3
   44          ]).   45:- use_module(library(http/http_open)).   46:- use_module(library(http/http_json)).   47:- use_module(library(http/json)).   48:- use_module(library(option)).   49:- use_module(library(uri)).   50
   51:- multifile
   52    es_server/2.                        % URL, Options

 es_get(+Path, -Result) is det

 es_put(+Path, +Data) is det

 es_post(+Path, +Data) is det

 es_post(+Path, +Data, -Result) is det

Low level access to the Elastic HTTP service. Path is either an atom or a /-separated segment list, e.g., Index/'_doc'.

Arguments:

Result

- is a JSON term represented as a dict.

   70es_get(Path, Result) :-
   71    es_url(Path, URL, Options),
   72    http_open(URL, In,
   73              [ status_code(Status)
   74              | Options
   75              ]),
   76    call_cleanup(reply(Status, In, Result), close(In)).
   77
   78es_put(Path, Data) :-
   79    es_url(Path, URL, Options),
   80    http_open(URL, In, [ method(put),
   81                         post(json(Data)),
   82                         status_code(Status)
   83                       | Options
   84                       ]),
   85    call_cleanup(ok_reply(Status, In), close(In)).
   86
   87es_post(Path, Data) :-
   88    es_url(Path, URL, Options),
   89    http_open(URL, In, [ post(json(Data)),
   90                         status_code(Status)
   91                       | Options
   92                       ]),
   93    call_cleanup(ok_reply(Status, In), close(In)).
   94
   95es_post(Path, Data, Result) :-
   96    es_url(Path, URL, Options),
   97    http_open(URL, In, [ post(json(Data)),
   98                         status_code(Status)
   99                       | Options
  100                       ]),
  101    call_cleanup(reply(Status, In, Result), close(In)).

 es_add(+Index, +Data, -Reply, +Options) is det

Add a document to the index Index. Data is a Prolog dict to represent the document. This must satisfy the type as defined by es_create_index/2.

  109es_add(Index, Data, Reply, Options) :-
  110    option(id(Id), Options),
  111    !,
  112    es_post(Index/'_doc'/Id, Data, Reply).
  113es_add(Index, Data, Reply, _Options) :-
  114    es_post(Index/'_doc', Data, Reply).

 es_search(+Index, +Query, -Result) is det

Search using Query, returning a list of Prolog dicts that express the result.

  121es_search(Index, For, Result) :-
  122    es_post(Index/'_search', For, Result).

 es_create_index(+Index, +Mapping) is det

 es_delete_index(+Index) is det

Create or delete an index. Note that deleting an index also deletes all its data.

  130es_create_index(Index, Mapping) :-
  131    es_put(Index,
  132           #{mappings:
  133             #{properties:Mapping}
  134            }).
  135
  136es_delete_index(Index) :-
  137    es_url(Index, URL, Options),
  138    http_open(URL, In, [ method(delete),
  139                         status_code(Status)
  140                       | Options
  141                       ]),
  142    call_cleanup(ok_reply(Status, In), close(In)).

 es_url(+Path, -URL, -Options) is det

Etablish the Elastic URL from Path and the options for connecting as required by http_open/3. The latter typically contains TLS authentication if this is used.

  150es_url(Path, URL, [connection('Keep-alive')|Options]) :-
  151    es_server(URL0, Options),
  152    path_segments(Path1, Path),
  153    uri_edit(path(Path1), URL0, URL).
  154
  155:- public tls_verify/5.  156tls_verify(_SSL, _ProblemCert, _AllCerts, _FirstCert, verified) :-
  157    !.
  158tls_verify(_SSL, _ProblemCert, _AllCerts, _FirstCert, hostname_mismatch) :-
  159    !.
  160tls_verify(_SSL, _ProblemCert, _AllCerts, _FirstCert, _Error) :-
  161    fail.

 ok_reply(+Status, +Stream) is det

 reply(+Status, +Stream, -Reply) is det

Handle the HTTP reply. Either succeed (2xx for ok_reply/2), return a Prolog dict with the JSON reply (2xx, for reply/3) or raise an exception holding with a Prolog dict holding the details.

  170ok_reply(Status, _In) :-
  171    between(200, 299, Status),
  172    !.
  173ok_reply(Status, In) :-
  174    json_read_dict(In, Result, []),
  175    print_message(error, es_error(Status, Result)).
  176
  177reply(Status, In, Reply) :-
  178    between(200, 299, Status),
  179    !,
  180    json_read_dict(In, Reply, []).
  181reply(Status, In, null) :-
  182    json_read_dict(In, Result, []),
  183    throw(error(es_error(Status, Result), _)).

 path_segments(?Path, ?Segments) is det

Convert between `a/b/c/... and 'a/b/c/...'`

  189path_segments(Path, Segments) :-
  190    nonvar(Path),
  191    !,
  192    atomic_list_concat(Segments, /, Path).
  193path_segments(Path, Path) :-
  194    atomic(Path),
  195    !.
  196path_segments(Path, Segments) :-
  197    phrase(segments(Segments), List),
  198    atomic_list_concat(List, /, Path).
  199
  200segments(A/B) -->
  201    !,
  202    segments(A),
  203    segments(B).
  204segments(A) -->
  205    [A].
  206
  207		 /*******************************
  208		 *            MESSAGES		*
  209		 *******************************/
  210
  211:- multifile
  212    prolog:message//1,
  213    prolog:error_message//1.  214
  215prolog:error_message(es_error(Code, Message)) -->
  216    [ 'Elastic search: got reply ~w:'-[Code], nl,
  217      '   ~@'-[print_term(Message, [output(current_output)])],
  218      nl
  219    ]