Зміни в документі 2. Налаштування бандла

Остання зміна 2024/07/11 11:49 автором Ashterix

Від 2.1 до 1.1 Від 4.1 до 3.1

Від версії 3.1

редаговано Ashterix
дата 2024/07/11 11:40

Змінити коментар: Немає коментарів для цієї версії

До версії 2.1

редаговано Ashterix
дата 2024/07/11 09:58

Змінити коментар: Немає коментарів для цієї версії

Необроблений
Надані

Підсумок

Властивості сторінки (2 змінено, 0 додано, 0 видалено)

Подробиці

Властивості сторінки

Назва

@@ -1,1 +1,1 @@
--2. Налаштування бандла
++tmp

Вміст

@@ -1,377 +1,0 @@
--{{box cssClass="floatinginfobox" title="**Зміст**"}}
--{{toc/}}
--{{/box}}
--
--{{info}}
--Конфігурація зазнала суттєвих змін і не має зворотної сумісності з версією 6.
--{{/info}}
--
--(% class="wikigeneratedid" %)
--Всі налаштування бандла знаходяться в файлі {{code language="none"}}config/packages/ufo_json_rpc.yaml{{/code}}.
--
--(% class="wikigeneratedid" %)
--Є можливість налаштувати параметри захисту API та деякі параметри формату даних, що віддається при запиті документації.
--
--= Блок {{code language="none"}}security{{/code}} =
--
--Наразі єдиним механізмом захисту доступу до вашого API є встановлення перевірки ключа доступу (api_token).
--
--== Параметри {{code language="none"}}protected_api{{/code}} та {{code language="none"}}protected_doc{{/code}} (boolean) ==
--
--(% class="wikigeneratedid" %)
--Ці параметри вказує чи мають бути захищені API методи та документація, відповідно.
--
--(% class="wikigeneratedid" %)
--За замовченням апі методи захищені, а документація відкрита.
--
--{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
--ufo_json_rpc:
--    security:
--        protected_api: true     # Protection API requests
--        protected_doc: false    # Protection API documentation
--{{/code}}
--
--(% id="cke_bm_164641S" style="display:none" %) (%%)Якщо ви захищаєте ваш API через {{code language="none"}}protected_api{{/code}}, вам необхідно налаштувати токени, по яким буде відкритий доступ.
--
--Перш за все, треба визначитися з назвою токену.
--
--== Параметр {{code language="none"}}token_name{{/code}} ==
--
--Компонент {{code language="none"}}RpcSecurity{{/code}} буде шукати в заголовках запиту специфічний ключ, який ви можете встановити в налаштуваннях пакету, значення за замовченням {{code language="none"}}token_name: 'Ufo-RPC-Token'{{/code}}, ви можете встановити будь-яке інше значення яке відповідає наступним вимогам.
--
--{{spoiler title=" Вимоги до формування заголовків протоколу HTTP"}}
--Вимоги до назв заголовків HTTP не є строго регульованими щодо капіталізації, оскільки HTTP заголовки нечутливі до регістру. Однак, існують деякі загальні практики і стандарти, які зазвичай дотримуються для кращої читабельності та узгодженості:
--
--- Капіталізація: Зазвичай назви HTTP заголовків пишуться з використанням CamelCase, де кожне слово починається з великої літери, наприклад, Content-Type, User-Agent, Accept-Encoding. Це не впливає на технічну обробку заголовків, але робить їх легше читати.
--- Унікальність: Кожен заголовок повинен мати унікальну назву у контексті одного HTTP запиту або відповіді. Не можна використовувати однакові назви для різних заголовків у тому самому запиті чи відповіді.
--- Спеціальні заголовки: Існують заголовки, які використовуються специфічно для контролю поведінки кешування (Cache-Control), безпеки (Strict-Transport-Security), аутентифікації (Authorization), тощо.
--- Норми RFC: Вимоги до заголовків регулюються документами RFC, які визначають стандарти для протоколів Інтернету. Наприклад, загальні заголовки і їхнє використання описані в RFC 7231.
--{{/spoiler}}
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--
--Параметр {{code language="none"}}clients_tokens{{/code}}
--
--Тепер слід вказати масив клієнтськіх токенів, які будуть мати доступ до API.
--
--Тут є певна варіативність.
--
--=== Токени в параметрах ===
--
--(% class="box errormessage" %)
--(((
--**НЕ РЕКОМЕНДОВАНО!!!**
--\\Цей підхід допускається лише для локального тестування API
--)))
--
--Є можливість прописати токени хардкодом прямо в файлі налаштувань.
--
--Це погано з позиції безпеки, якщо код зберігається в публічному репозиторію, то до цього токену буде мати доступ кожен.
--
--{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
--ufo_json_rpc:
--    security:
--        token_name: 'Ufo-RPC-Token'
--        clients_tokens:
--            - 'ClientTokenExample'  # hardcoded token example. Importantly!!! Replace or delete it!
--
--{{/code}}
--
--=== Токени в змінних оточення ===
--
--Це найбільш доцільний механізм у разі, якщо ви розробляєте сервіс для розподіленого бекенду, що написаний на SOA (Сервіс-Орієнтована Архітектура). Зазвичай, в такому випадку, вам треба відкрити доступ до апі одному або обмеженій кількості клієнтських додатків і оновлення ключів не буде відбуватися занадто часто.
--
--В такому випадку можна прописати токени в змінних оточення (файл {{code language="none"}}.env.local{{/code}} під час локальної розробки). Цей механізм достатньо безпечний з боку збереження доступів.
--
--(((
--{{code language="ini" layout="LINENUMBERS" title=".env.local"}}
--TOKEN_FOR_APP_1=9363074966579432364f8b73b3318f71
--TOKEN_FOR_APP_2=456fg87g8h98jmnb8675r4445n8up365
--{{/code}}
--
--{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
--ufo_json_rpc:
--    security:
--        token_key_in_header: 'Ufo-RPC-Token'
--        clients_tokens:
--            - '%env(resolve:TOKEN_FOR_APP_1)%'   # token example from .env.local
--            - '%env(resolve:TOKEN_FOR_APP_2)%'   # token example from .env.local
--{{/code}}
--)))
--
--=== Токени для користувача ===
--
--Припускаю, що у вас може виникнути потреба зробити персональні ключі для користувачів вашого додатку, можливо ви захочете впровадити ліміти або інші обмеження.
--В такому випадку вам не потрібно вказувати перелік токенів в конфігах, ви можете зберігати їх в базі даних або іншому місці згідно вашій бізнес-логіки. Єдина вимога, у вас має бути сервіс, який вміє перевіряти чи існує наданий токен.
--
--Для того, щоб JsonRpcServer міг використовувати вашу логіку, доведеться реалізувати власний клас, що реалізує інтерфейс {{code language="none"}}Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator{{/code}}
--
--{{code language="php" layout="LINENUMBERS" title="==== Приклад власного валідатора токенів ===="}}
--<?php
--
--namespace App\Services\RpcSecurity;
--
--use App\Services\UserService;
--use Symfony\Component\Security\Core\Exception\UserNotFoundException;
--use Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator;
--use Ufo\RpcError\RpcInvalidTokenException;
--
--class UserTokenValidator implements ITokenValidator
--{
--
--    public function __construct(protected UserService $userService) {}
--
--    public function isValid(string $token): true
--   {
--        try {
--            $this->userService->getUserByToken($token);
--            return true;
--        } catch (UserNotFoundException $e) {
--            throw new RpcInvalidTokenException(previous: $e);
--        }
--    }
--}
--{{/code}}
--
--(% class="box warningmessage" %)
--(((
--**ВАЖЛИВО!!!**
--Метод {{code language="none"}}isValid{{/code}} має повертати {{code language="none"}}true{{/code}} якщо токен існує і валідний, або викидати {{code language="none"}}Ufo\RpcError\RpcInvalidTokenException{{/code}} в іншому разі.
--)))
--
--Після цього вам потрібно в файлі {{code language="none"}}config/services.yaml{{/code}} прописати що класи, що мають залежність від інтерфейса {{code language="none"}}ITokenValidator{{/code}} мають приймати ваш новий клас.
--
--{{code language="yaml" layout="LINENUMBERS" title="config/services.yaml"}}
--parameters:
--   # some parameters list
--   # ...
--
--services:
--   # some services list
--   # ...
--
--    Ufo\JsonRpcBundle\Security\Interfaces\ITokenValidator:
--        class: App\Services\RpcSecurity\UserTokenValidator
--{{/code}}
--
--= Блок {{code language="none"}}async{{/code}} =
--
--Цей блок для налаштування [[асинхронного транспорту>>doc:docs.JsonRpcBundle.functionality.async.WebHome]].
--
--Додайте параметр {{code language="none"}}rpc_async{{/code}} який містить рядок у форматі DSN. Цей рядок є конфігурацією [[Symfony Messenger>>https://symfony.com/doc/current/messenger.html]], він вказує на асинхронний транспорт по якому RPC Server буде очікувати вхідні запити якщо у вас запущений консюмер ({{code language="none"}}php bin/console messenger:consume rpc_async{{/code}}). Для більш детального розуміння цього процесу читайте документацію [[Symfony Messenge>>https://symfony.com/doc/current/messenger.html]].
--
--{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
--ufo_json_rpc:
--    async:
--        rpc_async: '%env(resolve:RPC_TRANSPORT_DSN)%'
--
--{{/code}}
--
--(% class="box warningmessage" %)
--(((
--Це налаштування має на увазі, що у вас в змінних оточення встановлена змінна RPC_TRANSPORT_DSN що містить DSN рядок.
--)))
--
--= Блок {{code language="none"}}docs{{/code}} =
--
--Цей блок налаштовує деякі параметри генерації документації коли ви робите GET запит на RPC Server.
--
--(% class="box infomessage" %)
--(((
--Починаючи з версії 7, JsonRpcBundle генерує API документацію, що відповідає специфікації [[OpenRpc>>https://spec.open-rpc.org/]]
--)))
--
--* {{code language="none"}}project_name{{/code}}: Назва проєкту, що буде відображена в документації
--* {{code language="none"}}project_description{{/code}}: Опис проєкту
--* {{code language="none"}}project_version{{/code}}: Поточна версія вашого API
--* {{code language="none"}}async_dsn_info{{/code}}: Відповідає за відображення в документації інформації про асинхронний транспорт
--* (% id="cke_bm_826282S" style="display:none" %) {{code language="none"}}validations.symfony_asserts{{/code}}(%%): <bool> Відповідає за відображення рядку очікувань валідації для параметра (якщо ви використовуєте [[валідацію>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]])
--
--{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
--ufo_json_rpc:
--    docs:
--        project_name: 'My Project'
--        project_description: 'My project description'
--        project_version: '1.0'
--        # Optional response details
--        async_dsn_info:  false          # Provide information about API that work asynchronously
--        validations:
--            symfony_asserts: false      # Indicates if an array of Symfony validation constraints is used
--
--{{/code}}
--
--==== **Приклад документації ** ====
--
--{{code language="json" layout="LINENUMBERS" title="GET: /api"}}
--{
--    "envelope": "JSON-RPC-2.0/UFO-RPC-6",
--    "contentType": "application/json",
--    "description": "",
--    "transport": {
--        "sync": {
--            "scheme": "http",
--            "host": "example.com",
--            "path": "/api",
--            "method": "POST"
--        },
--        "async": {
--            "scheme": "amqp",
--            "user": "{user}",
--            "pass": "{pass}",
--            "host": "async_rabbit",
--            "port": 5672,
--            "path": "/%2f/json-rpc"
--        }
--    },
--    "methods": {
--        ...
--    }
--}
--{{/code}}
--
--{{info}}
--Не переймайтеся щодо безпеки ваших авторизаційних даних. що містяться в DSN.
--
--Документатор побудований таким чином, що перед виводом інформації про DSN він видаляє дані про користувача і його пароль, а також інші секретні дані, як то токени, секретні ключі, тощо.
--
--Шаблон, по якому відбувається захист {{code language="none"}}/([\w\d_]*(?:secret|access|token|key)[_\w]*)=((?:\w|\d)+(?=&?))/{{/code}}.
--
--Приклад:
--
--{{code language="json" layout="LINENUMBERS" title="RPC_TRANSPORT_DSN=https://sqs.eu-west-3.amazonaws.com/123456789012/messages?access_key=AKIAIOSFODNN7EXAMPLE&secret_key=j17M97ffSVoKI0briFoo9a"}}
--{
--    "async": {
--        "scheme": "https",
--        "host": "sqs.eu-west-3.amazonaws.com",
--        "path": "/123456789012/messages",
--        "query": "access_key={access_key}&secret_key={secret_key}"
--    }
--}
--{{/code}}
--{{/info}}
--
--=== Параметр {{code language="none"}}validations{{/code}} ===
--
--Відповідає за відображення в документації методів додаткових блоків, що вказують на вимоги до валідації даних.
--
--Наразі цей блок має два можливих налаштування:
--
--* {{code language="none"}}json_schema: <bool>{{/code}}
--* {{code language="none"}}symfony_asserts: <bool>{{/code}}
--
--У всіх опцій в цьому параметрі значення за замовченням {{code language="none"}}false{{/code}}, тобто ці блоки не будуть відображатися в документації.
--Якщо ви потребуєте якийсь з цих блоків інформації при запиті документації, то встановіть значення в {{code language="none"}}true{{/code}}.
--
--{{code language="yaml" layout="LINENUMBERS" title="config/packages/ufo_json_rpc.yaml"}}
--ufo_json_rpc:
--    docs:
--        project_name: 'My Project'
--        project_description: ''
--        project_version: null
--        # Optional response details
--        async_dsn_info:  false          # Provide information about API that work asynchronously
--        validations:
--            symfony_asserts: false      # Indicates if an array of Symfony validation constraints is used
--
--{{/code}}
--
--==== **Приклад документації ** ====
--
--(% class="box infomessage" %)
--(((
--В цьому прикладі я видалив вміст обʼєктів symfony_assertions для спрощення прикладу.
--Детальніше про валідацію методів дивись сторінку **[[Валідація процедур>>doc:docs.JsonRpcBundle.add_rpc_service.assertions.WebHome]]**
--)))
--
--{{code language="json" layout="LINENUMBERS" title="GET: /api"}}
--{
--   "openrpc":"1.2.6",
--   "info":{
--      "title":"My Project",
--      "description":"My project description",
--      "contact":{
--         "name":"ufo-tech/json-rpc-bundle",
--         "url":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
--      },
--      "license":{
--         "name":"MIT"
--      },
--      "version":"1.0"
--   },
--   "servers":[
--      {
--         "url":"https://mysite.com/api",
--         "description":"Json-RPC api server from UFO Tec\n\nUFO Tech, or Universal Flexible Open Technologies, is an initiative aimed at providing PHP developers with tools to create complex yet user-friendly solutions for modern web applications and service-oriented architectures.",
--         "name":"UFO Json-RPC Server v.7.0.0",
--         "x-method":"POST",
--         "x-ufo":{
--            "envelop":"JSON-RPC-2.0/UFO-RPC-7.0.0",
--            "transport":{
--               "sync":{
--                  "scheme":"https",
--                  "host":"mysite.com",
--                  "path":"/api",
--                  "method":"POST"
--               },
--               "async":{
--                  "scheme":"amqp",
--                  "user":"{user}",
--                  "pass":"{pass}",
--                  "host":"mysite.com",
--                  "port":5672,
--                  "path":"/%2f/json-rpc"
--               }
--            },
--            "documentation":{
--               "json-rpc":"https://www.jsonrpc.org/specification",
--               "ufo-tech/json-rpc-bundle":"https://docs.ufo-tech.space/bin/view/docs/JsonRpcBundle/?language=en"
--            }
--         }
--      }
--   ],
--   "methods":[
--      {
--         "name":"getUserNameByUuid",
--         "tags":[
--            {
--               "name":"App\\Api\\UserApiService"
--            }
--         ],
--         "summary":"Get username by id",
--         "params":[
--            {
--               "name":"userId",
--               "description":"User Id format uuid",
--               "required":true,
--               "schema":{
--                  "type":"string"
--               },
--               "x-ufo-assertions": "new Assert\\Uuid()"
--            }
--         ],
--         "result":{
--            "name":"string",
--            "description":"User Name",
--            "schema":{
--               "type":"string"
--            }
--         }
--      }
--   ]
--}
--{{/code}}

Зміни в документі 2. Налаштування бандла

Підсумок

Подробиці

Навігація

Дочірні Cторінки

Нещодавно переглянуті