1c/OpenIntegrations
1
0
Fork 0
mirror of https://github.com/Bayselonarrend/OpenIntegrations.git synced 2025-11-29 22:27:42 +02:00
Code Issues Releases Activity

Доработка документации по внешним компонентам

Browse Source
This commit is contained in:
Anton Titovets
2025-04-01 23:18:40 +03:00
parent d9d7898aec
commit a94c206086
23 changed files with 11493 additions and 3110 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
docs/en/md/Instructions/MySQL.md vendored
View File

@@ -9,6 +9,21 @@ sidebar_class_name: MySQL
This section is dedicated to the PostMySQLgreSQL database library. On this page, all the steps necessary to start working are described
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
<img src={require('../../static/img/addin.png').default} class="tipimage" />
<div class="addin">An external component is used to implement some functions in this library<br/>
Please review the ["About external components"](/docs/Start/Component-requirements) section before getting started</div>
</div>
<div class="theme-admonition theme-admonition-caution admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--warning">
<img src={require('../../static/img/lock.png').default} class="tipimage" />
<div class="addin">This library requires **OpenSSL 3.x** to run on Linux <br/>
Learn more: <a href="/docs/Start/Component-requirements#openssl" class="orangelink">"Using OpenSSL in External Components"</a></div>
</div>
## About implemented methods

15
docs/en/md/Instructions/PostgreSQL.md vendored
View File

@@ -9,6 +9,21 @@ sidebar_class_name: PostgreSQL
This section is dedicated to the PostgreSQL database library. On this page, all the steps necessary to start working are described
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
<img src={require('../../static/img/addin.png').default} class="tipimage" />
<div class="addin">An external component is used to implement some functions in this library<br/>
Please review the ["About external components"](/docs/Start/Component-requirements) section before getting started</div>
</div>
<div class="theme-admonition theme-admonition-caution admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--warning">
<img src={require('../../static/img/lock.png').default} class="tipimage" />
<div class="addin">This library requires **OpenSSL 3.x** to run on Linux <br/>
Learn more: <a href="/docs/Start/Component-requirements#openssl" class="orangelink">"Using OpenSSL in External Components"</a></div>
</div>
## About implemented methods
This library has two parts: basic methods, like connecting and executing SQL queries, and a small ORM for common operations like CREATE, SELECT, INSERT, DELETE, and so on. Working through the ORM and through the query texts executed through the `ExecuteSQLQuery()` function is technically the same: the ORM simply generates the SQL query text based on the layouts, but then also calls them through this function

7
docs/en/md/Instructions/RCON.md vendored
View File

@@ -9,6 +9,13 @@ sidebar_class_name: RCON
This section is dedicated to the library for working with the RCON. On this page, all the steps necessary to start working are described
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
<img src={require('../../static/img/addin.png').default} class="tipimage" />
<div class="addin">An external component is used to implement some functions in this library<br/>
Please review the ["About external components"](/docs/Start/Component-requirements) section before getting started</div>
</div>
## About the library
RCON (Remote Console) is a protocol used to remotely control servers, most commonly game servers. It allows administrators or owners to execute commands on a server from the outside, without having to physically access the machine where the server is running.

7
docs/en/md/Instructions/SQLite.md vendored
View File

@@ -9,6 +9,13 @@ sidebar_class_name: SQLite
This section is dedicated to the SQLite database library. On this page, all the steps necessary to start working are described
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
<img src={require('../../static/img/addin.png').default} class="tipimage" />
<div class="addin">An external component is used to implement some functions in this library<br/>
Please review the ["About external components"](/docs/Start/Component-requirements) section before getting started</div>
</div>
## About implemented methods
This library has two parts: basic methods, like connecting and executing SQL queries, and a small ORM for common operations like CREATE, SELECT, INSERT, DELETE, and so on. Working through the ORM and through the query texts executed through the `ExecuteSQLQuery()` function is technically the same: the ORM simply generates the SQL query text based on the layouts, but then also calls them through this function

28
docs/en/md/Instructions/Start.md vendored
View File

@@ -105,16 +105,22 @@ Some features of this documentation that will help you use it more effectively a
<hr/>
## Structure of modules
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
The project's common modules come in two types:
## Support the project
- Service
- OPI_Tools
- OPI_Cryptography
- Modules for direct interaction with APIs
- OPI_Telegram, OPI_VK...
:::warning
It is not recommended to use the methods of utility modules in other parts of your configuration (if you plan to update to new versions in the future). To maintain backward compatibility, the number/purpose of parameters and the return types for API interaction methods do not change, but this does not apply to utility modules, which can be modified in any way for optimization and adaptation to new requirements. If you need functionality from the utility modules, it is recommended to copy it separately.
:::
<img src={require('../../static/img/heartnstar.png').default} width='320px' align="right" class="hearthnstar"/>
If you like the OpenIntegrations project and want to support it, you can do so in one of the following ways:
+ Give a ⭐ to [this repository](https://github.com/Bayselonarrend/OpenIntegrations)
+ Upvote OPI articles [on InfoStart](https://infostart.ru/profile/1793672/)
If you'd like, you can also financially support the project via Tribute or YooMoney by clicking one of the icons below or using the links in the right-hand sidebar of repository page
<a href="https://t.me/tribute/app?startapp=dnje"><img src={require('../../static/img/tribute.png').default} width='40px' /></a>
<a href="https://yoomoney.ru/to/4100117914332065"><img src={require('../../static/img/yoomoney.png').default} width='40px' /></a>
**Thanks for supporting our project!**
</div>

15
docs/en/md/Instructions/TCP.md vendored
View File

@@ -9,6 +9,21 @@ sidebar_class_name: TCP
This section is dedicated to the library for working with the TCP. On this page, all the steps necessary to start working are described
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
<img src={require('../../static/img/addin.png').default} class="tipimage" />
<div class="addin">An external component is used to implement some functions in this library<br/>
Please review the ["About external components"](/docs/Start/Component-requirements) section before getting started</div>
</div>
<div class="theme-admonition theme-admonition-caution admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--warning">
<img src={require('../../static/img/lock.png').default} class="tipimage" />
<div class="addin">This library requires **OpenSSL 3.x** to run on Linux <br/>
Learn more: <a href="/docs/Start/Component-requirements#openssl" class="orangelink">"Using OpenSSL in External Components"</a></div>
</div>
## About implemented methods
This library provides several ready-made methods for working as a TCP client. The standard scheme of interaction with the server is as follows:

98
docs/en/md/Start/Component-requirements.md vendored Normal file
View File

@@ -0,0 +1,98 @@
---
sidebar_position: 3
---
# About external components (AddIns)
Some tools in the OPI toolkit utilize **external components (AddIns)** — dynamic libraries written in Rust that contain functions whose implementation would be difficult or impossible using 1C/OS alone. While working with OPI’s functionality, you won’t interact with these components directly, their presence introduces certain challenges and non-obvious considerations. These are documented in this section.
## Compatibility
All external components added to OPI are compiled for x64 and x32 versions of Windows and Linux. They are stored in special ZIP archives containing four library files—one for each platform. However, while there are no issues with their usage on Windows, on Linux these components depend on two things being present in the system: `glibc` and (not for all components) `OpenSSL`.
### glibc
**glibc** is a C library that provides system calls and core functions like open, malloc, printf, etc. It always comes preinstalled in x86 Linux distributions, though version numbers may vary. The minimum required version for OPI components is **2.17**. This version corresponds to distributions such as CENTOS 7, RHEL 7, Fedora 19, Debian 8 and Ubuntu 12.04 (around 2013-2014). On older distributions, libraries using external components won't work.
### OpenSSL
Libraries with TLS-related functionality links to system libraries of **OpenSSL version 3.x** - `libssl.so.3` and `libcrypto.so.3`. This is a relatively new version that comes by default in distributions starting with CENTOS 9, RHEL 9, Fedora 36, Debian 12 and Ubuntu 22.04 (approximately 2022-2023). For older distributions (using OpenSSL 1.1 or earlier), OpenSSL 3.x must be installed or built from source separately.
## Usage Information
You can find information about a library using external components on the first page of its documentation in footnotes like these:
<div class="theme-admonition theme-admonition-info admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--info">
<img src={require('../../static/img/addin.png').default} class="tipimage" />
<div class="addin">An external component is used to implement some functions in this library<br/>
Please review the ["About external components"](/docs/Start/Component-requirements) section before getting started</div>
</div>
<div class="theme-admonition theme-admonition-caution admonition_node_modules-@docusaurus-theme-classic-lib-theme-Admonition-Layout-styles-module alert alert--warning">
<img src={require('../../static/img/lock.png').default} class="tipimage" />
<div class="addin">This library requires **OpenSSL 3.x** to run on Linux <br/>
Learn more: <a href="/docs/Start/Component-requirements#openssl" class="orangelink">"Using OpenSSL in External Components"</a></div>
</div>
If such footnotes are missing, the library was implemented without external components
<hr/>
## FAQ
Некоторые вопросы о работе и реализации внешних компонент, несвязанные напрямую с работой ОПИ
**1. Can external components be rebuilt?**
Yes. The Rust source code is located in the repository at [src/addins](https://github.com/Bayselonarrend/OpenIntegrations/tree/main/src/addins). The compiled components must be placed in a ZIP archive with a [manifest file](https://github.com/Bayselonarrend/OpenIntegrations/blob/main/src/addins/MANIFEST.XML). You can then replace the archive from the release, depending on the distribution used. Additionally, the [build.bat](https://github.com/Bayselonarrend/OpenIntegrations/blob/main/src/addins/build.bat) file in src/addins describes the process for building release versions of the components.
**2. Can OpenSSL-dependent external components be rebuilt for OpenSSL 1.1/1.1.1k?**
My attempts to do this were unsuccessful: even if you successfully links to libssl.so.1.1, the Rust project dependencies (particularly `native-tls`) require functions that either weren't implemented in OpenSSL 1.1 or were modified in 3.x. Downgrading crate versions to the point where security issues begin to appear didn't help. However, if you know how to work around this, I'd be very grateful if you could share your solution in Issues
**3. Why is OpenSSL dynamically linked rather than statically linked?**
Static linking (embedding a pre-built OpenSSL within the component) comes with numerous issues: potential conflicts when multiple `.so` files with static linking attempt to use shared system resources simultaneously (`ERR_STATE`, `/dev/random`, etc.); increases file sizes due to needing a separate OpenSSL copy in each component; inability to update the OpenSSL version without rebuilding projects; and other problems. For these reasons, we decided against using static linking.
**4. Can I see the full dependency list for a specific component?**
In the source directory of each component, you'll find a `dependencies.log` file - this contains the output of `ldd` and `strings | grep GLIBC` for the x64 version of the .so file after compilation. Here's an example of what it looks like:
```
"MAIN ---"
linux-vdso.so.1 (0x00007ffe4cd2e000)
libssl.so.3 => not found
libcrypto.so.3 => not found
libm.so.6 => /lib64/libm.so.6 (0x00007f1ed1fb9000)
libpthread.so.0 => /lib64/libpthread.so.0 (0x00007f1ed1d99000)
libc.so.6 => /lib64/libc.so.6 (0x00007f1ed19c2000)
libdl.so.2 => /lib64/libdl.so.2 (0x00007f1ed17be000)
/lib64/ld-linux-x86-64.so.2 (0x00007f1ed2562000)
GLIBC_2.2.5
GLIBC_2.3
GLIBC_2.3.4
GLIBC_2.14
GLIBC_2.17
```
You can also obtain this information yourself by extracting the ZIP archive containing the library files and applying these same (or other) analysis tools to the `.so` file corresponding to your platform.
## Technical information about building and development
+ All components are cydlib libraries built in Rust, based on the [addin1c crate by medigor](https://crates.io/crates/addin1c)
+ Linux builds are created using [zigbuild](https://github.com/rust-cross/cargo-zigbuild) on OracleLinux 9.1 (WSL)
+ Profile.release:
```toml
lto = "fat" # Enable Link Time Optimization
codegen-units = 1 # Reduce number of codegen units to increase optimizations.
panic = "abort" # Abort on panic
strip = true # Automatically strip symbols from the binary.
opt-level = "z"
```

1
docs/en/md/sidebars.js vendored
View File

@@ -39,6 +39,7 @@
{ type: 'category', link: {type: 'doc', id:'Instructions/GoogleSheets'}, label: 'Google Sheets', className: 'GoogleSheets', items:[{type: 'autogenerated', dirName: 'Google_Sheets'}]},
{ type: 'category', link: {type: 'doc', id:'Instructions/PostgreSQL'}, label: 'PostgreSQL', className: 'PostgreSQL', items:[{type: 'autogenerated', dirName: 'PostgreSQL'}]},
{ type: 'category', link: {type: 'doc', id:'Instructions/SQLite'}, label: 'SQLite', className: 'SQLite', items:[{type: 'autogenerated', dirName: 'SQLite'}]},
{ type: 'category', link: {type: 'doc', id:'Instructions/MySQL'}, label: 'MySQL', className: 'MySQL', items:[{type: 'autogenerated', dirName: 'MySQL'}]},
],
},
{