API: A Service to manage the REST API. More...

#include <api.h>

Inheritance diagram for jazz_main::API:

Public Member Functions
	API (pLogger a_logger, pConfigFile a_config, pChannels a_channels, pVolatile a_volatile, pPersisted a_persisted, pCore a_core, pModelsAPI a_model)

virtual pChar const	id ()

StatusCode	start ()

StatusCode	shut_down ()

MHD_StatusCode	get_static (pMHD_Response &response, pChar p_url, bool get_it=true)

MHD_Result	return_error_message (pMHD_Connection connection, pChar p_url, int http_status)

MHD_StatusCode	http_put (pChar p_upload, size_t size, ApiQueryState &q_state, int sequence)

MHD_StatusCode	http_delete (ApiQueryState &q_state)

MHD_StatusCode	http_get (pMHD_Response &response, ApiQueryState &q_state)

Public Member Functions inherited from jazz_bebop::BaseAPI
	BaseAPI (pLogger a_logger, pConfigFile a_config, pChannels a_channels, pVolatile a_volatile, pPersisted a_persisted)
	Creates a BaseAPI service without starting it.

StatusCode	start ()

StatusCode	shut_down ()

bool	parse (ApiQueryState &q_state, pChar p_url, int method, bool recurse=false)

bool	block_from_const (pTransaction &p_txn, pChar p_const, bool make_tuple=false)

virtual StatusCode	header (StaticBlockHeader &hea, ApiQueryState &what)

virtual StatusCode	get (pTransaction &p_txn, ApiQueryState &what)

virtual StatusCode	put (ApiQueryState &where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	remove (ApiQueryState &what)

pChannels	get_channels ()

pVolatile	get_volatile ()

pPersisted	get_persisted ()

Public Member Functions inherited from jazz_elements::Container
	Container (pLogger a_logger, pConfigFile a_config)

StatusCode	start ()

StatusCode	shut_down ()

void	enter_read (pTransaction p_txn)

void	enter_write (pTransaction p_txn)

void	leave_read (pTransaction p_txn)

void	leave_write (pTransaction p_txn)

StatusCode	new_block (pTransaction &p_txn, int cell_type, int dim, int fill_tensor=FILL_NEW_DONT_FILL, int stringbuff_size=0, const char p_text=nullptr, char eol='\n', AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, int num_items, StaticBlockHeader p_hea[], Name p_names[], pBlock p_block[], AttributeMap dims=nullptr, AttributeMap att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from, pBlock p_row_filter, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pTuple p_from, pChar name, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from_text, int cell_type, pKind p_as_kind=nullptr, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, pBlock p_from_raw, pChar p_fmt=nullptr, bool ret_as_string=false, AttributeMap *att=nullptr)

StatusCode	new_block (pTransaction &p_txn, int cell_type)

StatusCode	new_block (pTransaction &p_txn, Index &index)

virtual StatusCode	new_transaction (pTransaction &p_txn)

virtual void	destroy_transaction (pTransaction &p_txn)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what, pBlock p_row_filter)

virtual StatusCode	get (pTransaction &p_txn, pChar p_what, pChar name)

virtual StatusCode	locate (Locator &location, pChar p_what)

virtual StatusCode	header (StaticBlockHeader &hea, pChar p_what)

virtual StatusCode	header (pTransaction &p_txn, pChar p_what)

virtual StatusCode	put (pChar p_where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	new_entity (pChar p_where)

virtual StatusCode	remove (pChar p_where)

virtual StatusCode	copy (pChar p_where, pChar p_what)

virtual StatusCode	exec (pTransaction &p_txn, Locator &function, pTuple p_args)

virtual StatusCode	modify (Locator &function, pTuple p_args)

virtual StatusCode	as_locator (Locator &result, pChar p_what)

virtual StatusCode	get (pTransaction &p_txn, Locator &what)

virtual StatusCode	get (pTransaction &p_txn, Locator &what, pBlock p_row_filter)

virtual StatusCode	get (pTransaction &p_txn, Locator &what, pChar name)

virtual StatusCode	locate (Locator &location, Locator &what)

virtual StatusCode	header (StaticBlockHeader &hea, Locator &what)

virtual StatusCode	header (pTransaction &p_txn, Locator &what)

virtual StatusCode	put (Locator &where, pBlock p_block, int mode=WRITE_AS_BASE_DEFAULT)

virtual StatusCode	new_entity (Locator &where)

virtual StatusCode	remove (Locator &where)

virtual StatusCode	copy (Locator &where, Locator &what)

StatusCode	unwrap_received (pTransaction &p_txn)

StatusCode	unwrap_received (pTransaction &p_txn, pBlock p_maybe_block, int rec_size)

void	base_names (BaseNames &base_names)

Public Member Functions inherited from jazz_elements::Service
	Service (pLogger a_logger, pConfigFile a_config)

void	log (int loglevel, const char *message)

void	log_printf (int loglevel, const char *fmt,...)

bool	get_conf_key (const char *key, int &value)

bool	get_conf_key (const char *key, double &value)

bool	get_conf_key (const char *key, std::string &value)

Private Member Functions
bool	find_myself ()

StatusCode	load_statics (pChar p_base_path, pChar p_relative_path, int rec_level)

bool	expand_url_encoded (pChar p_buff, int buff_size, pChar p_url)

Private Attributes
pCore	p_core
	The Core.

pModelsAPI	p_model
	The ModelsAPI.

Index	www
	A map from url to locators to serve static files.

int	remove_statics
	A flag to remove the statics from persistence on shutdown configured by REMOVE_STATICS_ON_CLOSE.

Additional Inherited Members
Data Fields inherited from jazz_bebop::BaseAPI
TenBitPtrLUT	base_server
	A LUT to convert TenBitsAtAddress(base) into a pContainer.

Data Fields inherited from jazz_elements::Service
pLogger	p_log
	The logger.

pConfigFile	p_conf
	The configuration file.

Protected Member Functions inherited from jazz_bebop::BaseAPI
bool	parse_locator (Locator &loc, pChar p_url)

int	move_const (pChar p_buff, int buff_size, pChar p_url, pChar p_base=nullptr)

StatusCode	get_right_local (pTransaction &p_txn, ApiQueryState &q_state)

StatusCode	get_right_remote (pTransaction &p_txn, ApiQueryState &q_state)

StatusCode	get_left_local (pTransaction &p_txn, ApiQueryState &q_state)

StatusCode	put_left_local (ApiQueryState &q_state, pBlock p_block)

Protected Member Functions inherited from jazz_elements::Container
void *	malloc (size_t size)

pBlock	block_malloc (size_t size)

void	lock_container ()

void	unlock_container ()

StatusCode	destroy_container ()

int	from_hex (char c)

Protected Attributes inherited from jazz_bebop::BaseAPI
pChannels	p_channels
	The Channels container.

pVolatile	p_volatile
	The Volatile container.

pPersisted	p_persisted
	The Persisted container.

Protected Attributes inherited from jazz_elements::Container
int	max_transactions
	The configured ONE_SHOT_MAX_TRANSACTIONS.

uint64_t	warn_alloc_bytes
	Taken from ONE_SHOT_WARN_BLOCK_KBYTES.

uint64_t	fail_alloc_bytes
	Taken from ONE_SHOT_ERROR_BLOCK_KBYTES.

uint64_t	alloc_bytes
	The current allocation in bytes.

pTransaction	p_buffer
	The buffer for the transactions.

pTransaction	p_free
	The free list of transactions.

bool	alloc_warning_issued
	True if a warning was issued for over-allocation.

Lock32	_lock_
	A lock for the deque of transactions.

Detailed Description

API: A Service to manage the REST API.

This service parses and executes http queries. It is aware and redistributes to all the appropriate services. It is called directly by the http callback http_request_callback().

Constructor & Destructor Documentation

◆ API()

jazz_main::API::API	(	pLogger	a_logger,
		pConfigFile	a_config,
		pChannels	a_channels,
		pVolatile	a_volatile,
		pPersisted	a_persisted,
		pCore	a_core,
		pModelsAPI	a_model
	)

Constructor for the API service.

Parameters

a_logger	A pointer to the Logger object.
a_config	A pointer to the ConfigFile object.
a_channels	A pointer to the Channels object.
a_volatile	A pointer to the Volatile object.
a_persisted	A pointer to the Persisted object.
a_core	A pointer to the Core object.
a_model	A pointer to the ModelsAPI object.

Member Function Documentation

◆ id()

pChar const jazz_main::API::id ( )

virtual

Return object ID.

Returns: A string identifying the object that is especially useful to track uplifts and versions.

Reimplemented from jazz_bebop::BaseAPI.

◆ start()

StatusCode jazz_main::API::start ( )

virtual

Starts the API service

Returns: SERVICE_NO_ERROR if successful, an error code otherwise.

Configuration-wise the API has just two keys:

STATIC_HTML_AT_START: which defines a path to a tree of static objects that should be uploaded on start.
REMOVE_STATICS_ON_CLOSE: removes the whole database Persisted //static when this service closes.

Besides that, this function initializes global (and object) variables used by the parser (mostly CharLUT).

Reimplemented from jazz_elements::Service.

◆ shut_down()

StatusCode jazz_main::API::shut_down ( )

virtual

Shuts down the Persisted Service

Returns: SERVICE_NO_ERROR if successful, an error code otherwise.

Configuration-wise the API has just one key:

REMOVE_STATICS_ON_CLOSE: removes the whole database Persisted //static when this service closes.

Reimplemented from jazz_elements::Service.

◆ get_static()

MHD_StatusCode jazz_main::API::get_static	(	pMHD_Response &	response,
		pChar	p_url,
		bool	get_it = `true`
	)

Check a non-API url into and return the static object related with it.

Parameters

response	A valid (or error) MHD_Response pointer with the resource, status, mime, etc.
p_url	The http url (that has already been checked not to start with //)
get_it	If true (default), it actually gets it as a response, otherwise it just check if it exists.

Returns: Some error code or SERVICE_NO_ERROR if successful.

◆ return_error_message()

MHD_Result jazz_main::API::return_error_message	(	pMHD_Connection	connection,
		pChar	p_url,
		int	http_status
	)

Finish a query by delivering the appropriate message page.

Parameters

connection	The MHD connection passed to the callback function. (Needed for MHD_queue_response()ing the response.)
p_url	The url that failed.
http_status	The http status error (e.g., MHD_HTTP_NOT_FOUND)

Returns: A valid answer for an MHD callback. It is an integer generated by MHD_queue_response() and returned by the callback.

This function searches for a persistence block named ("www", "httpERR_%d") where d is the code in decimal and serves it as an answer.

◆ http_put()

MHD_StatusCode jazz_main::API::http_put	(	pChar	p_upload,
		size_t	size,
		ApiQueryState &	q_state,
		int	sequence
	)

Execute a put block using some one-shot block as an intermediate buffer.

Parameters

p_upload	A pointer to the data uploaded with the http PUT call.
size	The size of the data uploaded with the http PUT call.
q_state	The structure containing the parts of the url successfully parsed.
sequence	SEQUENCE_FIRST_CALL, SEQUENCE_INCREMENT_CALL or SEQUENCE_FINAL_CALL. (See below)

Returns: MHD_HTTP_CREATED if SEQUENCE_FINAL_CALL is successful, MHD_HTTP_OK if any othe call is successful, or any HTTP error status code.

This function is only called after a successful parse() of an HTTP_PUT query. It is not private because it is called for the callback, but it is not intended for any other context.

Internals

It supports any successful HTTP_PUT syntax, that is:

APPLY_NOTHING: With or without node, mandatory base, entity and key. APPLY_RAW & APPLY_TEXT: With or without node, mandatory base, entity and key. APPLY_URL: With or without node and just a base.

In all cases, calls with a node (it can only be l_node) q_state.url contains exactly what has to be forwarded.

Call logic:

SEQUENCE_FIRST_CALL comes first and is mandatory. On success, the functions keeps the data in a block stored in a pTransaction in q_state.rr_value.p_extra (that pointer will be returned in successive call of the same PUT query). SEQUENCE_INCREMENT_CALL may or may not come, if it does, it must allocate bigger blocks and store more data in the same pTransaction. SEQUENCE_FINAL_CALL is called just once, it must destroy the pTransaction when done

◆ http_delete()

MHD_StatusCode jazz_main::API::http_delete ( ApiQueryState & q_state )

Execute an http DELETE of a block using the block API.

Parameters

q_state The structure containing the parts of the url successfully parsed.

Returns: true if successful, log(LOG_MISS, "further details") for errors.

This function is only called after a successful parse() of an HTTP_DELETE query. It is not private because it is called for the callback, but it is not intended for any other context.

Internals

It supports any successful HTTP_PUT syntax, that is:

APPLY_NOTHING: With or without node, mandatory base and entity, with of without a key. APPLY_URL: With or without node and just a base.

In all cases, calls with a node (it can only be l_node) q_state.url contains exactly what has to be forwarded.

◆ http_get()

MHD_StatusCode jazz_main::API::http_get	(	pMHD_Response &	response,
		ApiQueryState &	q_state
	)

Execute a get block using the instrumental API.

Parameters

response	A valid (or error) MHD_Response pointer with the resource. It will only be used on success.
q_state	The structure containing the parts of the url successfully parsed.

Returns: MHD_HTTP_OK if successful, or a valid http status error.

This function is only called after a successful parse() of HTTP_GET and HTTP_HEAD queries. It is not private because it is called for the callback, but it is not intended for any other context.

Internals

It supports, basically everything, which is, all apply in many versions:

APPLY_NOTHING, APPLY_NAME, APPLY_URL, APPLY_FUNCTION, APPLY_FUNCT_CONST, APPLY_FILTER, APPLY_FILT_CONST, APPLY_RAW, APPLY_TEXT, APPLY_ASSIGN_NOTHING, APPLY_ASSIGN_NAME, APPLY_ASSIGN_URL, APPLY_ASSIGN_FUNCTION, APPLY_ASSIGN_FUNCT_CONST, APPLY_ASSIGN_FILTER, APPLY_ASSIGN_FILT_CONST, APPLY_ASSIGN_RAW, APPLY_ASSIGN_TEXT, APPLY_ASSIGN_CONST, APPLY_NEW_ENTITY, APPLY_GET_ATTRIBUTE, APPLY_SET_ATTRIBUTE and APPLY_JAZZ_INFO

To simplify, this top level function decomposes the logic into smaller parts.

◆ find_myself()

bool jazz_main::API::find_myself ( )

private

Changes the current name until.

Try to find what is the IP, port of the current node in case no match by name with the configuration was found.

Returns: true if successful.

◆ load_statics()

StatusCode jazz_main::API::load_statics	(	pChar	p_base_path,
		pChar	p_relative_path,
		int	rec_level
	)

private

Push a copy of all the files in the path (searched recursively) to the Persisted database "static" and index their names to be found by get_static().

It also assigns attributes:

BLOCK_ATTRIB_URL == same relative path after the root path.
BLOCK_ATTRIB_MIMETYPE guessed from the file extension (html, js, png, etc.)
BLOCK_ATTRIB_LANGUAGE == en-us

Parameters

p_base_path	The path to the tree of webpage statics.
p_relative_path	The relative path that becomes the url with a file name added, starting with /.
rec_level	The level of recursion (from 0 to MAX_RECURSE_LEVEL_ON_STATICS)

Returns: Some error code or SERVICE_NO_ERROR if successful.

◆ expand_url_encoded()

bool jazz_main::API::expand_url_encoded	(	pChar	p_buff,
		int	buff_size,
		pChar	p_url
	)

private

Copy while percent-decoding a string into a buffer. Only RFC 3986 section 2.3 and RFC 3986 section 2.2 characters accepted.

Parameters

p_buff	A buffer to store the result.
buff_size	The size of the output buffer (ending zero included).
p_url	The input string.

Returns: 'true' if successful. Possible errors are wrong %-syntax, wrong char range or output buffer too small.

See https://en.wikipedia.org/wiki/Percent-encoding This is utf-8 compatible, utf-8 chars are just percent encoded one byte at a time.

The documentation for this class was generated from the following files:

api.h
api.cpp

Public Member Functions

Private Member Functions

Private Attributes

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ API()

Member Function Documentation

◆ id()

◆ start()

◆ shut_down()

◆ get_static()

◆ return_error_message()

◆ http_put()

Internals

Call logic:

◆ http_delete()

Internals

◆ http_get()

Internals

◆ find_myself()

◆ load_statics()

◆ expand_url_encoded()