You've already forked OpenIntegrations
mirror of
https://github.com/Bayselonarrend/OpenIntegrations.git
synced 2025-12-21 23:57:40 +02:00
158 lines
6.7 KiB
Plaintext
Vendored
158 lines
6.7 KiB
Plaintext
Vendored
---
|
|
id: Extensions
|
|
title: Standard library and extensions
|
|
sidebar_position: 4
|
|
---
|
|
|
|
This section describes the primary methods for processing incoming requests: using functions from the Open Integration Package (OpenIntegrations) standard library and custom extension functions.
|
|
|
|
## OpenIntegrations methods (standard library)
|
|
|
|
As previously mentioned in the documentation, each handler is characterized by a function responsible for generating responses to incoming requests. By default, Melezh includes the complete set of methods from the Open Integration Package libraries - these methods can be selected as processing functions when configuring individual handlers.
|
|
|
|
When configuring handlers via the command line interface, you can refer to the Open Integration Package documentation for:
|
|
- Correct library (command) names
|
|
- Function names and their arguments
|
|
- Examples of return values that will be included in response bodies
|
|
|
|
|
|
|
|
:::warning
|
|
Library names must be specified in CLI application format. Examples: `telegram` or `gdrive` (Google Drive)
|
|
:::
|
|
|
|
<br/>
|
|
|
|
When using the web interface, you can select the desired library and function from dropdown menus during handler configuration:
|
|
|
|
|
|
|
|
<hr/>
|
|
|
|
## Extensions
|
|
|
|
In addition to the standard set of functions from the OpenIntegrations, Melezh can use methods from custom `.os` scripts as handler functions. For their correct interpretation, three conditions must be met:
|
|
|
|
+ The method must be a function that returns binary data, a string, or a JSON-serializable collection (array, structure, or mapping without non-serializable fields)
|
|
+ The script file must have a correct name (no spaces, preferably using Latin characters), `.os` extension, and be placed in the `extensions/Modules` subdirectory of the main Melezh directory
|
|
|
|
Windows (default):
|
|
```
|
|
C:\Program Files (x86)\OInt\share\oint\lib\melezh\extensions\Modules
|
|
```
|
|
|
|
Linux:
|
|
```
|
|
share/oint/lib/melezh/extensions/Modules
|
|
```
|
|
|
|
OneScript, as OPM package:
|
|
```
|
|
<OneScript directory>/lib/melezh/extensions/Modules
|
|
```
|
|
|
|
+ The method must include a documentation comment in the following format:
|
|
|
|
```bsl
|
|
// Method name
|
|
// Method description
|
|
//
|
|
// Parameters:
|
|
// Field1 - String - Field 1 value - field1
|
|
// Field2 - String - Field 2 value - field2
|
|
// Field3 - String - Field 3 value - field3
|
|
//
|
|
// Return:
|
|
// Structure Of KeyAndValue - Returned value
|
|
```
|
|
|
|
This is the standard EDT comment format but with three distinctive features: the second line is a brief function description (optional), parameters have a fourth description block - CLI style argument name, the parameter description cannot use the `-` character except as block separators
|
|
|
|
:::warning
|
|
Using `-` in parameter description text will cause an error
|
|
:::
|
|
|
|
<br/>
|
|
|
|
In the standard distribution, the `extensions/Modules` directory contains a `RequestsEcho.os` module that can be used as an example when creating new extensions:
|
|
|
|
```bsl title="RequestsEcho.os"
|
|
|
|
// Fields echo
|
|
//
|
|
// Parameters:
|
|
// Field1 - String - Field 1 value - field1
|
|
// Field2 - String - Field 2 value - field2
|
|
// Field3 - String - Field 3 value - field3
|
|
//
|
|
// Returns:
|
|
// Structure Of KeyAndValue - Echo
|
|
Function FieldsEcho(Val Field1, Val Field2, Val Field3 = "") Export
|
|
Return New Structure("field1,field2,field3", Field1, Field2, Field3);
|
|
EndFunction
|
|
|
|
```
|
|
|
|
In the Web console selection list, this module will be displayed as follows:
|
|
|
|
|
|
|
|
To use it as a library when working via the terminal (command line), specify the module file name without the extension as the `library` option.
|
|
|
|
It is also important to note that when using extension functions, especially for handlers with the GET or POST + `form-data` types, values may arrive in unsuitable data types. Melezh does not automatically convert data into the required types, except for those that can be explicitly determined during JSON reading or parsing of `multipart/form-data` (binary or string).
|
|
|
|
To convert values to the appropriate types, you can use custom converters or those already used in the core functions of the Open Integration Package. They can be found in the module [OPI_TypeConversion](https://github.com/Bayselonarrend/OpenIntegrations/blob/main/src/en/OInt/tools/Modules/OPI_TypeConversion.os)
|
|
|
|
:::important
|
|
It is recommended to keep backup copies of extension modules in another location, as in certain cases, updates or removal of Melezh, as well as image rebuilding (if Docker is used), may result in the deletion of these files! You can also specify any third-party directory for storing extensions using the `ext_path` setting (recommended)
|
|
:::
|
|
|
|
## `--melezhcontext`
|
|
|
|
In some cases, simply obtaining processed data and returning a response body is not sufficient. For low-level interaction — such as modifying the response status code and headers, as well as directly accessing request data — extensions can utilize the reserved option `melezhcontext`.
|
|
|
|
To use this option, specify `melezhcontext` as the CLI name for any of the function's parameters within the documentation comment:
|
|
|
|
|
|
```bsl title="Static.os (Melezh extension)"
|
|
|
|
// Get file from folder
|
|
//
|
|
// Parameters:
|
|
// Directory - String - Folder path - catalog
|
|
// FileName - String - File name with extension - file
|
|
// MIME - String - MIME type - mime
|
|
// Context - Arbitrary - Request context - melezhcontext
|
|
//
|
|
// Returns:
|
|
// Structure Of KeyAndValue, BinaryData - file data or error info
|
|
Function GetFileFromFolder(Val Directory, Val FileName, Val MIME, Val Context) Export
|
|
|
|
Directory = StrReplace(Directory, "\", "/");
|
|
Directory = ?(StrEndsWith(Directory, "/"), Directory, Directory + "/");
|
|
|
|
FullPath = Directory + FileName;
|
|
PathFile = New File(FullPath);
|
|
|
|
If Not PathFile.Exist() Then
|
|
|
|
Context.Response.StatusCode = 404;
|
|
Context.Response.ContentType = "application/json";
|
|
Return New Structure("result,error", False, "Not Found");
|
|
|
|
Else
|
|
Context.Response.ContentType = MIME;
|
|
Return New BinaryData(FullPath);
|
|
EndIf;
|
|
|
|
EndFunction
|
|
|
|
|
|
```
|
|
|
|
This option is not displayed in the list of arguments within the web interface and always contains a value of type `HTTPContext` (a native web server type in OneScript used for handling HTTP requests and responses). For more information on working with context, see the [OneScript repository](https://github.com/EvilBeaver/OneScript/tree/develop/src/OneScript.Web.Server).
|
|
|
|
:::important
|
|
When implementing custom extensions — particularly those involving `melezhcontext` — it is strongly recommended to use the OneScript version of Melezh during development. This enables running the project in debug mode (e.g., in VSCode) and setting breakpoints to inspect runtime values and context data.
|
|
:::
|