Довідник з конфігурації

OxPHP налаштовується через змінні середовища, а також через один необов’язковий файл: .oxphpdeny — правила заборони шляхів, що читаються з кореня DOCUMENT_ROOT. Кожне налаштування має типове значення, тож розгортання взагалі без конфігурації працює одразу.

Булеві значення

Змінні, позначені як булеві, приймають фіксований канонічний набір значень без урахування регістру й з обрізанням пробілів:

• істинні: on, true, 1, yes
• хибні: off, false, 0, no

Будь-яке непорожнє значення поза цим набором — наприклад, друкарська помилка на кшталт ture — одразу зупиняє запуск з помилкою, у якій названо змінну. Так помилкову конфігурацію буде виявлено ще до надходження трафіку, а не тоді, коли прапорець мовчки перемкнеться не в той бік.

Незадана змінна або порожнє присвоєння (FOO=) повертається до задокументованого типового значення. Порожнє значення навмисно трактується як незадане: підстановка в Docker Compose / Kubernetes на кшталт FOO=${FOO} дає FOO=, коли змінна на хості відсутня, і через це сервер не повинен відмовлятися стартувати.

Сервер

Розмір асинхронного середовища виконання

TOKIO_WORKERS типово дорівнює половині доступних ядер, і друга половина не простоює: вона належить пулу PHP-воркерів. Обидва набори потоків змагаються за ті самі ядра, тож розширити середовище виконання, не забравши тактів у застосунку, неможливо.

Підняти його до повної кількості ядер — це програш усюди, де пул уже має розмір, близький до цього числа. На 4-ядерній машині з пулом із 4 воркерів, що віддавав стиснуті відповіді, перехід від 2 потоків середовища виконання до 4 коштував 13% швидкості на JSON-тілі в 1,6 КБ і 26% на тілі в 5 КБ, та ще й спалив більше CPU, бо потоків стало більше, ніж ядер.

Піднімайте його там, де баланс інший: пул малий відносно машини або робота обмежена введенням-виведенням, а не PHP (проксійовані upstream-сервери, статичні файли, потокові відповіді), — тоді роботу виконує середовище виконання, а пул переважно чекає. Хоч би що ви змінили, стежте не лише за швидкістю, а й за пулом: oxphp_busy_workers порівняно з oxphp_workers_current покаже, куди пішли ядра. Зростання швидкості при дедалі більшій зайнятості пулу — справжній виграш; зростання швидкості при спорожнінні пулу зазвичай означає, що робота переїхала, а не що її стало виконано більше.

PHP-воркери

Розмір набору очікувачів

Скільки запитів може корисно чекати, залежить від того, як швидко пул їх обробляє. З W воркерами й обробником, що триває T мілісекунд, пул допускає W / T запитів за мілісекунду, тож бюджет у B мілісекунд може впустити приблизно W × B / T очікувачів. Усе, що понад це, чекає весь бюджет і все одно отримує відмову, увесь цей час тримаючи підключення й буферизоване тіло запиту.

Швидкість обслуговування на старті невідома, тож типове значення не може цього обчислити й навмисно щедре. Це пасує швидким обробникам, коли пул розгрібає глибоку чергу з великим запасом у межах бюджету, і надто багато для повільних: з 8 воркерами, обробником у 200 мс і типовою стелею в 1 с (бюджет, чинний щоразу, коли пул не скидає навантаження) вчасно може бути допущено лише близько 40 запитів, тоді як типове значення відкладає до 1024.

Значення, близьке до W × B / T, перетворює надлишок на негайний 529 замість 529 секундою пізніше. Скорочення QUEUE_WAIT_TIMEOUT_MS досягає того самого через інший множник. Одне врівноважує інше, і для повільного обробника менший бюджет зазвичай кращий важіль, бо він також обмежує, скільки клієнт чекає на відмову. B тут — чинний бюджет, який під перевантаженням є скороченим сервером значенням, а не налаштованою стелею. Прочитайте oxphp_admission_wait_budget_us, перш ніж підбирати розмір набору очікувачів за числом із конфігураційного файлу.

Набір обмежено вдруге, у байтах. Кожен очікувач тримає тіло свого запиту в пам’яті весь час очікування, тож обмеження в кількості запитів віддає обсяг утримуваної пам’яті на розсуд трафіку: ті самі 1024 очікувачі нічого не коштують на GET без тіла й гігабайти — на завантаженнях. QUEUE_MAX_WAITING_BYTES обмежує цю суму безпосередньо — понад неї запит із тілом одразу отримує відмову замість відкладення, тоді як запити без тіла чекають як зазвичай. Застосунку з великою кількістю завантажень, який має поглинати сплески, а не скидати їх, потрібне більше значення; контейнеру з жорстким лімітом пам’яті — менше. Відмови за кожним обмеженням рахуються окремо в oxphp_admission_refused_total (waiting_full — за кількістю, waiting_bytes — за пам’яттю), тож метрика підказує, яке налаштування крутити.

Адаптивний бюджет очікування

QUEUE_WAIT_TIMEOUT_MS — це стеля. Поки робота, яку допускає очікування, завершується для клієнтів, що вже пішли, сервер сам скорочує бюджет, і то круто, — це варто знати, перш ніж обирати стелю:

• Униз: бюджет зменшується вдвічі щоразу, коли чверть або більше з того, що почав пул, дісталося клієнтам, які вже пішли; вимірюється у вікні щонайменше з восьми розпочатих запитів, а не за фіксований інтервал.
• Нижня межа: одна шістдесят четверта стелі (15,6 мс за типового значення) або 10 мс, залежно від того, що більше, але ніколи не вище за саму стелю.
• Угору: бюджет повертається кроками по восьмій частині стелі, і лише поки черга спостерігається порожньою, а клієнтам, які пішли, дісталося менше чверті з того, що почав пул. Звичайний потік закритих вкладок і клієнтських тайм-аутів не тримає його внизу, а сервер, чия черга ніколи не спорожнюється, лишається на скороченому бюджеті, доки навантаження не спаде.

Оператор, який задав 1000, має очікувати, що під час епізоду чинним буде близько 15, тож пишіть алерти на очікування відносно пари oxphp_admission_wait_budget_us / oxphp_admission_wait_budget_ceiling_us, а не відносно налаштованого числа.

Скорочення запускають клієнти, які закривають підключення. Сукупність клієнтів, що перестають чекати без закриття, не дає жодного сигналу й лишає чинною стелю.

Запас для циклу прийняття підключень

Запит тримає своє підключення — і один із дозволів MAX_CONNECTIONS — від моменту надходження до моменту відповіді, хоч би що він робив у проміжку. Це охоплює три окремі групи, бо місце в черзі звільняється тієї миті, коли воркер забирає запит, ще до запуску скрипту:

• ті, що виконуються у воркері: щонайменше PHP_WORKERS, а в режимі воркерів більше, бо один потік мультиплексує файбери;
• ті, що в черзі, — до QUEUE_CAPACITY;
• відкладені на етапі допуску — до QUEUE_MAX_WAITING.

Лише третя група має стелю, похідну від MAX_CONNECTIONS. Тримайте PHP_WORKERS + QUEUE_CAPACITY + QUEUE_MAX_WAITING нижче за MAX_CONNECTIONS. Понад це характер збою змінюється на гірше: цикл прийняття бере дозвіл на підключення, перш ніж почати його обслуговувати, тож щойно шлях PHP утримує їх усі, цикл зупиняється, і клієнт, що надходить у цей момент, не отримує жодної відповіді замість 529 — чого балансувальник навантаження не може відрізнити від мертвого екземпляра, тоді як health-перевірка на INTERNAL_ADDR лишається зеленою, бо не проходить через жодне з цих обмежень.

Зупинка потрапляє в лог. Прийняття, якому доводиться чекати на дозвіл, пише WARN із назвою бюджету, а INFO про те, скільки цикл простояв, записується тієї миті, коли дозвіл надходить. Звіти обмежено за частотою, щоб сервер, який коливається навколо стелі, не перетворив власний лог на причину збою: зупинку, що починається за кілька секунд після вже зареєстрованої, спочатку притримано й зареєстровано, коли це вікно закривається, якщо вона ще триває; та, що завершується в межах вікна, не залишає жодного рядка. Метрики бачать кожну: oxphp_accept_stalled (gauge, доступний для читання, поки зупинка триває, бо внутрішній слухач не проходить через MAX_CONNECTIONS) і oxphp_accept_stalls_total (лічильник); див. довідник метрик. Клієнти, що надходять, усе одно не отримують відповіді замість помилки, але лог і метрики фіксують зупинку.

Сервер перевіряє це на старті й попереджає, коли сума досягає бюджету, називаючи кожне значення; oxphp config --check повідомляє те саме, не змінюючи свого вердикту чи коду виходу. Вважайте, що прибрати попередження — необхідно, але не достатньо: неактивні keep-alive підключення, запити статичних файлів і рукостискання в процесі теж тримають дозволи, і жодне з них на старті не порахувати.

Зменшення MAX_CONNECTIONS — звичайний шлях до попередження, бо типове QUEUE_CAPACITY обчислюється з кількості воркерів і не зменшується слідом — 7 воркерів і MAX_CONNECTIONS=1000 дають 7 + 896 + 500 проти бюджету в 1000. Зверніть увагу, яке налаштування крутити: саме лише збільшення MAX_CONNECTIONS попередження не прибирає, поки QUEUE_MAX_WAITING лишається типовим, бо це типове значення — половина MAX_CONNECTIONS і зростає разом із ним — за 7 воркерів сума встановлюється на 1799, і умова знімається лише від MAX_CONNECTIONS=1800 і вище. Зменште QUEUE_CAPACITY або задайте QUEUE_MAX_WAITING явно, а тоді збільште бюджет.

Для динамічного пулу (MIN:MAX) доданок тих, що виконуються, — це мінімум, та сама кількість, з якої обчислюються типові значення черги, тож пул, що виріс до максимуму, тримає більше, ніж показує сума.

Порівняння рахує підключення, тоді як бюджет витрачають запити, тож розгортання з переважно HTTP/2-трафіком цілком законно може перебувати вище за нього: одне підключення несе до H2_MAX_CONCURRENT_STREAMS запитів, тож ту саму чергу тримає лише частка підключень. Там попередження очікуване. Великий пул на стандартному бюджеті теж його досягає — автоматично підібраний пул із 39 воркерів дає 39 + 4992 + 4992 проти 10 000 — і на це варто зреагувати, а не ігнорувати.

Статичні й динамічні воркери

Задайте PHP_WORKERS одним числом для фіксованого пулу:

Задайте PHP_WORKERS як MIN:MAX для автоматичного масштабування:

У динамічному режимі OxPHP додає воркерів, коли всі зайняті, і прибирає їх, коли воркери простоюють довше за PHP_WORKERS_IDLE_SECONDS.

Як визначається кількість CPU

Кожне типове значення на цій сторінці, виражене через CPU (TOKIO_WORKERS, а також PHP_WORKERS — незадане, 0 або з 0 з будь-якого боку MIN:MAX), рахує CPU, на яких процесу дозволено виконуватися: його маску affinity (taskset, docker run --cpuset-cpus), знижену до квоти CPU контейнера, якщо її задано (docker run --cpus; cpu.max у cgroup v2, cpu.cfs_quota_us у v1). Квота округлюється вниз і рахується щонайменше як 1, тож --cpus=1.5 рахується як 1.

Два види обмежень не враховуються, і контейнер, стримуваний лише одним із них, отримує розмір за всіма CPU, які бачить:

• Вага CPU: docker run --cpu-shares, cpu.weight у cgroup v2, cpu.shares у v1. Вона визначає, як процесорний час, за який точиться конкуренція, ділиться із сусідами. Це не стеля, і жодна кількість CPU з неї не випливає.
• Обмеження, яке застосовується поза контейнером. Платформа може продавати частку машини й застосовувати обмеження там, де контейнер його не бачить. Наприклад, на DigitalOcean App Platform екземпляр, проданий як 1 vCPU, як було помічено, працював у пісочниці gVisor без квоти (cpu.cfs_quota_us дорівнює -1) і з 8 видимими CPU, тож типові значення дали 4 PHP-воркери, 4 потоки середовища виконання й чергу на 512.

На старті сервер логує кількість, те, що її визначило, і підсумкові PHP_WORKERS і TOKIO_WORKERS. Ось як це виглядає з docker run --cpus=1 на машині з 14 CPU:

• cpu_source дорівнює host, коли ні маска, ні квота не знизили кількість, affinity або cgroup quota — коли одна з них її знизила, і unknown — коли сервер не зміг цього визначити, бо не вдалося прочитати маску або кількість онлайн-CPU. Якщо сервер узагалі не зміг порахувати CPU, cpus дорівнює 4.
• host_cpus — це кількість CPU, які система повідомляє як онлайн (/sys/devices/system/cpu/online у Linux); маска чи квота її не знижують. Поле пропускається, якщо його не вдається прочитати. Середовище виконання контейнерів, яке переписує цей файл так, щоб він перелічував лише CPU контейнера, змушує звужену маску читатися як host.
• (auto) позначає значення, повністю залишене на типове: змінну не задано або вона порожня, або — для TOKIO_WORKERS — вона не є числом.

cpu_source зі значенням host на тарифі, який продав вам менше CPU, ніж показує cpus, — це саме описаний вище випадок.

Режим воркерів

Задайте WORKER_MODE_ENABLED=true і вкажіть в ENTRY_FILE bootstrap-скрипт воркера (наприклад, ENTRY_FILE=worker.php або ENTRY_FILE=../worker.php). Тоді PHP-воркери живуть між запитами, зберігаючи стан ініціалізації (автозавантажувачі, підключення до бази даних) у пам’яті. Воркери перезапускаються автоматично, коли перевищують WORKER_MAX_MEMORY_MIB або отримують три поспіль запити, що зазнали збою, а також на вимогу, коли застосунок викликає Worker::scheduleExit(); що зараховується до третього випадку, див. у розділі Перезапуск. Налаштування WORKER_MAX_REQUESTS із попередніх релізів застаріле й ігнорується: не задавайте жодного з них або перейдіть на Worker::scheduleExit().

Застаріле: INDEX_FILE і WORKER_FILE

Застарілі змінні INDEX_FILE і WORKER_FILE досі розбираються для зворотної сумісності. Якщо їх задано, вони пишуть на старті рядок логу рівня WARN і відображаються на нову модель:

Якщо задано і старі, і нові, перевагу мають ENTRY_FILE / WORKER_MODE_ENABLED. Мігруйте, коли вам зручно; застарілі форми буде видалено в одному з майбутніх релізів.

SAPI / PHP

Тайм-аути

Час виконання PHP обмежується власною ini-директивою PHP max_execution_time (і set_time_limit() під час виконання), а не змінною середовища OxPHP. Ця межа не поширюється на асинхронне завдання: потік пулу ASYNC_WORKERS не тримає дедлайну виконання, тож ні директива, ні set_time_limit() не обмежують того, що виконує завдання, диспетчеризоване через oxphp_async(). Натомість обмежуйте таке завдання аргументом тайм-ауту oxphp_async_await(); див. Асинхронні проміси.

Обмеження частоти запитів

Безпека

Спеціальне значення private розгортається в усі приватні мережі RFC-1918, loopback і link-local адреси (IPv4 та IPv6): 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, 127.0.0.0/8, 169.254.0.0/16, ::1/128, fc00::/7, fe80::/10.

Захист від клікджекінгу

Клікджекінг — це атака, під час якої ворожа сторінка вбудовує ваш сайт у невидимий <iframe> і хитрощами змушує користувача натиснути те, чого він не бачить: кнопку «так, видалити мій обліковий запис», покупку в один клік, OAuth-запит «авторизувати». Захист полягає в тому, щоб повідомити браузеру, хто, якщо хтось узагалі, може вбудовувати ваші сторінки у фрейм. Цим керує FRAME_OPTIONS.

Вбудовування регулюють два заголовки — застарілий X-Frame-Options (його розуміють усі браузери) і сучасний Content-Security-Policy: frame-ancestors (який переважає, коли присутні обидва), — тож OxPHP надсилає обидва, і політика діє однаково в старих і нових браузерах. Одне значення FRAME_OPTIONS відповідає відповідній парі:

Вибір значення. SAMEORIGIN — типове: воно блокує вбудовування з іншого походження, на яке насправді спирається клікджекінг, і водночас дозволяє вашим власним сторінкам вбудовувати одна одну — що багато застосунків роблять цілком законно (попередній перегляд в адмінці, віджети дашбордів, платіжні компоненти на тому самому походженні). Обирайте DENY, коли на вашому сайті ніщо й ніколи не має вбудовуватися у фрейм, навіть самим сайтом, — це найсуворіший варіант. Обирайте off лише тоді, коли керуєте вбудовуванням самі через повноцінний Content-Security-Policy, який встановлює ваш застосунок, — див. нижче.

Вбудовування зовнішніми походженнями. Жодне зі значень X-Frame-Options не може назвати конкретне дозволене походження (ALLOW-FROM вилучено зі стандарту). Щоб дозволити названій третій стороні вбудовувати ваші сторінки, задайте FRAME_OPTIONS=off і нехай ваш застосунок надсилає власний Content-Security-Policy з явним списком frame-ancestors, наприклад header("Content-Security-Policy: frame-ancestors 'self' https://partner.example.com");.

Заголовки застосунку мають перевагу. Серверні заголовки — це запасний варіант, який застосовується лише тоді, коли відповідь не містить такого заголовка: застосунок, що встановлює власний X-Frame-Options або Content-Security-Policy через PHP header(), зберігає його недоторканим. Обидва заголовки вбудовування трактуються як одна політика, тож сервер ніколи не суперечить застосунку:

• Якщо ваш застосунок встановлює X-Frame-Options, OxPHP пропускає свій запасний frame-ancestors (серверний CSP переважив би вибір вашого застосунку в сучасних браузерах).
• Якщо ваш застосунок встановлює Content-Security-Policy, що містить директиву frame-ancestors, OxPHP пропускає свій запасний X-Frame-Options (суворіший серверний X-Frame-Options блокував би зайве в застарілих браузерах, які ігнорують CSP).

Те саме правило пріоритету стосується X-Content-Type-Options, який OxPHP встановлює в nosniff у кожній відповіді: значення, встановлене застосунком, зберігається дослівно. Зауважте, що nosniff — єдине значення, яке щось робить: застосунок, що перевизначає його будь-чим іншим, мовчки вимикає захист від MIME-sniffing.

TLS

HTTP/2

Статичні файли

Стиснення

Кодування пропонується, коли COMPRESSION_ENCODINGS його містить і його рівень не 0; будь-якої з цих умов окремо досить, щоб його прибрати. Рівень поза своїм діапазоном або нечислове значення зупиняє запуск з помилкою, у якій названо змінну. Значення не обрізаються до меж діапазону.

Логування

Клієнт, що закриває підключення до того, як сервер відповів, логується на рівні debug, а не error. Це найпоширеніша подія, яку бачить публічний слухач (скасований fetch, закрита вкладка, проксі, у якого спрацював тайм-аут читання), і вона не є збоєм сервера, тож за типового LOG_LEVEL її не видно. Рахуйте такі події через oxphp_request_cancelled_total{reason="client_abort"} або підніміть LOG_LEVEL=debug, щоб бачити окремі підключення. Тайм-аути, які контролює сам сервер (HEADER_TIMEOUT_SECONDS), лишаються на рівні warn, а всі інші збої підключень — на рівні error.

Спостережуваність

OpenTelemetry

APM

Коли APM увімкнено, OxPHP автоматично перехоплює 34 внутрішні функції PHP (PDO, mysqli, cURL, Redis, Memcached, файлове введення-виведення), щоб створювати дочірні спани. PHP-функції oxphp_apm_*() реєструються незалежно від того, чи ввімкнено APM. Коли його вимкнено, функції спанів нічого не роблять і повертають контрольні значення. Виняток — oxphp_apm_trace(): вона все одно виконує свій колбек і повертає його значення, тож вимкнення APM ніколи не змінює того, що обчислює ваш застосунок.

Асинхронні воркери

Пул асинхронних воркерів обробляє фонові завдання в режимі «запустив і забув», що диспетчеризуються з PHP. Він окремий від пулу PHP-воркерів і не потрібен для звичайної обробки запитів.

Некоректне значення в будь-якій із цих трьох змінних (наприклад, ASYNC_WORKERS=8x) — помилка запуску: повернення до типового значення мовчки вимкнуло б пул або налаштувало його неправильно. Точно порожнє значення трактується як незадане.

Хуки середовища виконання

Хуки діють усередині файберів запитів у режимі воркерів і файберів асинхронних завдань. Поза файбером (контекст запиту в режимах traditional/framework/SPA, CLI) зберігається оригінальна нативна поведінка, включно з помилками перевірки аргументів. Коли хуки sleep увімкнено, сторонній код, що викликає sleep(), перестає займати потік воркера скрізь, де файбер можна призупинити (а це не скрізь; див. нижче), без жодних змін у коді. Скасування асинхронного завдання під час перехопленого sleep розмотує його з OxPHP\Async\AsyncException, а перехоплений sleep(), що призупиняється, повертає 0; значення, яке нативна функція повертає в разі переривання сигналом, виникає лише на блокувальному шляху нижче.

Як перевірити, що налаштування підхопилося

Сервер повідомляє встановлені категорії, у вигляді розібраного набору, у двох місцях. На внутрішньому сервері:

І з PHP — для розгортання, чий внутрішній сервер недоступний або не ввімкнений:

Обидва читають те саме значення й повідомляють набір, а не рядок: RUNTIME_HOOKS=all, RUNTIME_HOOKS=1 і RUNTIME_HOOKS=sleep, streams, net усі повертаються як ["sleep","streams","net"]. Порожній список означає, що жодного хука не встановлено. Таку відповідь ви отримаєте для незаданої змінної, для RUNTIME_HOOKS=0, для значення, що називає лише категорії, невідомі цій збірці, і для змінної з помилкою в назві. Значення, що змішує одне з іншим, — інша справа: RUNTIME_HOOKS=sleep,bogus читається як ["sleep"], тож непорожній список сам по собі не свідчить, що кожну назву було зрозуміло. Кожна нерозпізнана назва отримує власний рядок у лозі сервера на старті, і цей рядок — єдине місце, де їх названо. Перевіряйте після кожної зміни налаштування: нерозпізнана змінна середовища ніде не є помилкою, тож «помилка в назві» інакше проявиться лише як латентність.

Коли net лишається вимкненим

net повідомляється лише тоді, коли він справді діє. Вказаний без streams, він лишається вимкненим, і про це каже рядок у лозі сервера. На платформі, що не є Linux, там, де власний код сервера неможливо відрізнити від коду PHP на старті, або там, де poll() PHP не прив’язаний до того, який перехоплює сервер, він лишається вимкненим із рядком про те, що встановлення підключень і очікування TLS лишаються блокувальними. Тож net, відсутній у списку після того, як ви його запросили, — це і є відповідь, а не прогалина у звіті.

Єдине, чого список не каже, — де живе OpenSSL. Очікування, які робить OpenSSL (TLS-рукостискання, включно з тим, яким завершується підключення ssl://, а також читання й записи на TLS-потоці після активації шифрування), паркуються лише тоді, коли OpenSSL вбудовано в PHP, як в офіційних образах. Якщо OpenSSL завантажено як окреме спільне розширення (extension=openssl), ці очікування, наскільки може судити сервер, не належать самому PHP, тож вони займають потік воркера, тоді як встановлення підключень, unix:// та інші читання все одно призупиняються, а net усе одно повідомляється.

Де хуки sleep не призупиняють виконання

Там, де перемикання файбера заборонено, перехоплені sleep()/usleep() передають виклик вбудованій функції, яку вони замінили, а та чекає на потоці воркера й повертає те, що повертає. Тож sleep(), перерваний там сигналом, повертає кількість секунд, які він не доспав, як і поза файбером. (Перевірка аргументу в будь-якому разі належить хуку: він відхиляє будь-що більше за 4294967295, що неперехоплена вбудована функція приймає й обрізає.) Перемикання заблоковано всюди, де вихід із поточного фрейму був би небезпечним, і перелік нижче не вичерпний:

• усередині обробника declare(ticks) і всередині диспетчеризації сигналів pcntl (в обох випадках це справа самого PHP);
• поки будуються вхідні дані запиту;
• усередині FILTER_CALLBACK, досягнутого з filter_input_array(), якому передано масив визначень для окремих полів (див. примітку під $_GET у розділі Суперглобальні змінні);
• усередині обходів під час демонтажу, які запускають деструктори після того, як запит зазнав збою (після фатальної помилки або після запису в уже скасований запит), тож __destruct(), що засинає для затримки перед повтором, робить це, утримуючи потік.

Звичайне завершення запиту до них не належить: деструктори й функції завершення виконуються там із дозволеним перемиканням. oxphp_sleep() і oxphp_usleep() у кожному з цих місць теж ідуть блокувальним шляхом, тож звернення до них не є способом це обійти.

Файбер, запущений планувальником у просторі користувача (AMPHP, Revolt або простий new Fiber), — інший випадок: перемикання там не заблоковано, і планувальник нормально призупиняє та відновлює власні файбери, але OxPHP не може відновити контекст, який йому не належить, тож хук відступає з тієї самої причини, що й хук streams. Ідеться про файбер, запущений усередині запиту; запит у режимі воркерів сам є файбером, яким керує OxPHP, тож хуки до нього застосовуються нормально. Код усередині файбера, який запустив сам застосунок, спить на потоці воркера, і цю частку навантаження слід планувати так, ніби хук вимкнено.

Що охоплює хук streams

Хук streams робить кооперативними блокувальне читання з PHP-потоку сокета й очікування всередині stream_select(). Перш ніж на нього розраховувати, перевірте, що ваш клієнт чекає одним із цих двох способів або одним зі способів, які додає категорія net (нижче). Кілька поширених клієнтів так не роблять, і для них нічого не змінюється:

• ext/curl. curl_exec() і curl_multi_* працюють із сокетами самостійно, нижче рівня PHP-потоків, тож хук їх ніколи не бачить. Це стосується кожного HTTP-клієнта, побудованого на curl, — серед них Guzzle з обробником за замовчуванням. Клієнта на curl можна перемкнути на обробник обгортки потоків, який таки проходить через PHP-потоки.

• socket_select(). Це ext/sockets, інший API на сирих дескрипторах, і його не перехоплено. stream_select() — перехоплено. Те саме стосується очікування всередині stream_socket_accept(), яке теж не перехоплено.

• Потоки unix://, udp:// і udg://, пари сокетів, потоки з socket_export_stream() на сокетах, що не є TCP, а також ssl:///tls:// після активації шифрування. Їхні таблиці операцій приватні для PHP або для OpenSSL, тож хук streams до них не дістається. Категорія net — дістається: коли її вказано, читання потоку (fread(), fgets() тощо) на будь-якому з них призупиняє файбер так само, як на tcp://. Без net вони, як і раніше, тримають потік воркера (доки stream_socket_enable_crypto() не завершиться успішно, читання SSL-потоку делегуються звичайному читанню із сокета й призупиняються в будь-якому разі). stream_socket_recvfrom() — це не читання потоку: вона викликає recvfrom() напряму, без власного очікування PHP, яке можна було б призупинити, тож на сокеті udp:// чи udg:// вона тримає потік воркера, доки не надійде датаграма, навіть із net. socket_export_stream() створює потік того транспорту, який використовує сокет: UDP-, unix- або датаграмний unix-сокет стає потоком udp://, unix:// або udg://, TCP-сокет — звичайним потоком tcp:// (який уже охоплює сам лише streams), а сокет будь-якого іншого типу — загальним потоком, який має пара сокетів.

• Підключення й розв’язання DNS. З net встановлення підключення через транспорти потоків PHP призупиняє файбер: stream_socket_client(), fsockopen() і клієнти, побудовані на них. ftp_connect() і socket_connect() підключаються самостійно, поза рівнем потоків, і не охоплені. Розв’язання DNS теж не призупиняється: ім’я хоста розв’язується на потоці воркера ще до початку підключення, тож повільний резолвер цей потік тримає. Клієнт із власною мережевою бібліотекою (pdo_pgsql і pgsql через libpq, розширення memcached через libmemcached) підключається й чекає всередині цієї бібліотеки, якої не бачить жодна з категорій. Клієнт, що тримає підключення відкритим, у будь-якому разі виграє на кожному запиті.

  Встановлення постійного підключення — виняток, і воно охоплює більше, ніж pfsockopen() і STREAM_CLIENT_PERSISTENT: PDO_MySQL з PDO::ATTR_PERSISTENT, mysqli з префіксом хоста p: і phpredis із pconnect() теж відкривають свої потоки як постійні, і встановлення їхніх підключень тримає потік воркера на час очікування, як і до появи net. Причина — список постійних ресурсів. Постійний потік заноситься до нього під своїм ключем ще до підключення, тож другий файбер, що запитує той самий ключ, поки перший чекає, знайшов би потік без дескриптора, прийняв би його за мертве підключення й закрив би його під файбером, який ще підключається. Деякі клієнти дають кожному підключенню власний ключ (mysqlnd так і робить), і таким способом ці потоки ніхто не знайде, але сервер вирішує за тим, чи є потік постійним, а не за тим, хто міг би його знайти, тож вони теж тримають потік воркера. Вартість — це встановлення підключення, яке постійне підключення сплачує один раз, коли його вперше відкривають, а не читання й записи на ньому.

• MySQL через localhost. Клієнт MySQL читає localhost як «використай unix-сокет», а це не потік tcp://, тож хук streams його не бачить. Пишіть у DSN 127.0.0.1 або вкажіть net, який охоплює потоки unix://. Це стосується і PDO_MySQL, і mysqli, і це легко пропустити, бо все й далі працює, просто без виграшу.

• Записи. Лише з streams чекають тільки читання. Готовність до читання стабільна, доки дескриптором володіє один файбер і ніщо інше його не вичитує, тоді як місце в буфері відправлення надає й забирає віддалена сторона, тож файбер, розбуджений за готовністю до запису, може виявити, що вікно знову закрилося на момент виконання запису, після чого PHP блокує потік на весь свій тайм-аут у будь-якому разі. Тому запис, що заповнює буфер сокета, поводиться точно так, як без хука. На практиці це коштує небагато: час забирає очікування відповіді, а не передавання запиту ядру. (Записи все ж переглядаються, але лише заради одного: щоб знати, обмін якого файбера зараз несе підключення, — див. примітку про спільні підключення нижче. На підключенні, яким не користується жоден інший файбер, — а у звичайному випадку це кожне підключення, — запис іде нативним шляхом без змін.)

  З вказаним net запис, якому доводиться чекати на місце, теж призупиняє файбер, а дескриптор перевіряється знову після кожного пробудження, тож вікно, що тим часом закрилося, коштує ще одного призупинення, а не потоку воркера. Виняток — звичайний потік із нескінченним тайм-аутом (default_socket_timeout=-1): PHP надсилає на нього блокувальним send() і ніколи не чекає сам, тож призупиняти нічого, і запис тримає потік воркера так само, як без хука. TLS-потік із нескінченним тайм-аутом — інша справа: власний цикл OpenSSL чекає в poll() без обмеження, і це очікування призупиняється.

У цих межах хук зберігає нативний контракт: тайм-аути сокетів (stream_set_timeout(), default_socket_timeout) діють без змін, читання з вичерпаним тайм-аутом, як і раніше, повідомляє timed_out через stream_get_meta_data(), а ідентичність потоку не змінюється, тож socket_import_stream() і подібні функції працюють далі. Одне обмеження щодо тайм-ауту: дедлайн перевіряється лише раз на такт планувальника, тож спрацьовує не раніше за наступний такт — у найкращому разі через 100 мкс у режимі воркерів і 50 мкс в асинхронному пулі, а під навантаженням довше, бо такт триває стільки, скільки виконується те, що зараз виконує воркер. Асинхронний пул робить довші паузи, коли нічого не відбувається, але не довші за дедлайн, який він тримає: дедлайн читання чи запису скорочує паузу так, щоб вона закінчилася саме на ньому, тож довше очікування не робить тайм-аут пізнішим. З default_socket_timeout у 60 секунд більшість розгортань цього не помітять.

stream_select() перехоплюється так: хук чекає на дескриптори, названі в трьох його масивах, а тоді передає виклик PHP з тайм-аутом, встановленим у нуль, тож PHP, як і раніше, вирішує все, що ви можете спостерігати: кількість, що повертається, переписування масивів до готових потоків, попередження й помилки аргументів. Очікування пропускається — і виклик виконується точно так, як без хука, — щоразу, коли масиви містять щось, чого хук не бере на себе: потік читання з уже буферизованими даними (на який stream_select() відповідає з буфера, не дивлячись на дескриптор), потік, що взагалі не має дескриптора, елемент, який не є живим потоком (скажімо, закритий потік, залишений у масиві, — PHP відповідає на це помилкою, а не очікуванням), дескриптор, за готовністю якого ядро взагалі не стежитиме (звичайний файл — типовий випадок, і він вважається готовим тієї миті, коли ви питаєте), або дескриптор із номером від FD_SETSIZE і вище, який власний select() PHP відхиляє одразу. Остання межа — реальна стеля, а не формальність: зайнятий воркер може тримати понад 1024 відкриті дескриптори, і stream_select(), що називає один із них, завершується помилкою однаково з хуком і без нього.

Спільні підключення між конкурентними файберами

Одне підключення, спільне для конкурентних файберів, безпечне для клієнтів, яких захищає OxPHP, і нічого не дає. Це звичайна форма застосунку в режимі воркерів, а не крайній випадок: WordPress, Laravel і Symfony відкривають клієнтів бази даних і кешу один раз під час завантаження воркера й передають ті самі клієнти кожному запиту, і, не переписавши їхній рівень доступу до даних, від них не можна вимагати окремого підключення для кожного файбера.

Клієнтський протокол — це послідовність обмінів: записати команду, прочитати відповідь, — і на підключенні ніщо не позначає, де один обмін закінчується. Файбер, призупинений на читанні, призупинений посеред обміну, і команда другого файбера, що потрапляє туди, ламає протокол. Два клієнти справляються з цим по-різному, і жоден добре: mysqlnd відстежує стан свого підключення й відхиляє команду, ще нічого не надіславши, тоді як phpredis такої перевірки не має, і два файбери читають відповіді одне одного — дані одного запиту повертаються іншому без жодної помилки.

Тож файбер захоплює підключення, перш ніж ним скористатися, на обох рівнях, де це має відбуватися: на рівні операцій сокета, які тримають байти в порядку, і на рівні клієнтських точок входу PDO та mysqli, бо відмова mysqlnd відбувається до будь-якого введення-виведення, і нічого на рівні сокета не встигне її запобігти. Інший файбер, що звертається до того самого підключення, чекає, доки його не звільнять на рівні клієнта, де утримується лише ідентичність підключення; на рівні сокета він не чекає, а отримує відмову — так само, як відмову через тайм-аут сокета, — бо файбер, призупинений усередині операції на чужому потоці, тримав би вказівник, який власник може звільнити. phpredis теж захищено на рівні клієнта, метод за методом, саме з цієї причини. На рівні клієнта захоплюється саме підключення, а не PHP-об’єкт, що його тримає, тож постійне підключення, досяжне через кілька об’єктів PDO, рахується як одне, а підключення, відкрите через PDO::connect(), — який повертає власний підклас драйвера, а не PDO, — охоплюється, як і будь-яке інше.

Отже, виграш хука належить підключенням, які файбер відкриває для себе: асинхронному завданню, що робить власні HTTP-виклики чи запити до бази даних, запиту, що відкриває власного клієнта. Спільне підключення отримує назад потік воркера на час очікування, тож інші запити можуть виконувати роботу, не пов’язану з цим підключенням; власні ж обміни на ньому виконуються один за одним, точно як із вимкненим хуком. Варто знати чотири межі:

1. Файбер, який хоч раз виконав запит, тримає підключення до кінця свого запиту, бо кінець запиту — перший момент, що гарантовано настає після кінця обміну. Він тримає його й тоді, коли призупинений на чомусь іншому, тож запит, що виконав запит до бази, а тоді чекає на власну роботу, якій потрібне те саме підключення, чекає на самого себе; ці двоє роз’єднуються на межі, описаній нижче, а не просуваються далі.

2. Очікування завжди обмежене: меншим із max_execution_time і default_socket_timeout. Якщо не задано жодного, межа становить 30 секунд, бо серверний SAPI бере типові значення рушія: 30 для першого й 60 для другого; 60 від default_socket_timeout вона становить лише тоді, коли max_execution_time дорівнює 0. max_execution_time читається таким, яким його зараз має запит, бо set_time_limit() — це спосіб, у який запит заявляє, скільки він може виконуватися; default_socket_timeout читається таким, з яким процес стартував, бо це типовий дедлайн операції сокета, і запит, що звужує його для власного виклику (звична для бібліотеки річ, як і забути його повернути), не повинен скорочувати цю межу для запитів, що йдуть за ним на тому самому воркері. Понад межу виклик повертається до незахищеної поведінки й пояснює причину в лозі сервера: для PDO і mysqli його передають клієнтові, чия власна відмова виконати команду посеред обміну — це помилка, яку застосунок уже обробляє, тоді як для phpredis, який такої відмови не має й натомість прочитав би чужу відповідь, кидається RedisException і нічого не надсилається.

   Один виклик PDO — виняток і тут, і для коду, що виконується поза будь-яким файбером (нижче): PDO::rollBack() на постійному підключенні, яке тримає інший файбер, виявивши на ньому відкриту транзакцію, нічого не надсилає й повертає false, бо ця транзакція належить власникові, і ROLLBACK, надісланий між його командами, завершив би її. Помилка, яку він повідомляє так, як велить режим помилок, — це помилка, яку підключення вже зберігає, і вона може бути помилкою власника. Власний демонтаж об’єкта PDO теж прив’язано до власника. Поки запит чи завдання тримає постійне підключення, знищення дескриптора на ньому відкочує відкриту там транзакцію й запускає очищення драйвера наприкінці запиту, лише якщо власник був останнім, хто користувався цим дескриптором (створив його або відтоді викликав через нього один із методів PDO, які захищає OxPHP), хоч би де дескриптор знищувався, включно зі збирачем циклів PHP, що працює в іншому запиті. Будь-який інший дескриптор пропускає обидві дії. На підключенні, яке ніхто не тримає, кожен дескриптор виконує обидві, як і раніше.

   Конфлікт на рівні сокета не має власної межі, бо ніколи не чекає: операція одразу завершується невдачею так, як за тайм-ауту, тож stream_get_meta_data() повідомляє timed_out. Це може коштувати більше, ніж сам виклик: клієнт вільний сприйняти відхилену операцію як щось гірше за невдалу команду, і mysqlnd так і робить з обох боків обміну. Запис, що нічого не надсилає, позначає підключення як втрачене й закриває його, читання, що повертається ні з чим, позначає його втраченим на місці, і кожна наступна команда на ньому отримує відповідь із цього стану, не торкаючись мережі. Втрачається все підключення, а не один виклик, — доти, доки щось тримає дескриптор. Захоплення на рівні клієнта, описане вище, — це те, що взагалі не дає командам захищеного клієнта дійти до такої відмови; протокол, написаний вручну на сирому сокеті, має трактувати відхилену операцію будь-якого типу так само, як закрите підключення. Тож два файбери, кожен з яких тримає те, на що чекає інший, роз’єднуються на цій межі, а не чекають одне на одного вічно.

   Код, що виконується поза будь-яким файбером, узагалі не може чекати на захоплення, і до нього застосовується лише рівень сокета. У режимі воркерів із RUNTIME_HOOKS=streams це насамперед деструктор, який цикл воркера запускає між запитами, коли збирає цикли, поки інші запити призупинені. Операція сокета, яку він виконує і яка мала б чекати, на підключенні, власник якого призупинений на ньому в очікуванні своєї відповіді, одразу завершується невдачею так, як за тайм-ауту, і нічого не надсилає; у будь-який інший момент вона виконується. Рівень клієнта там не застосовується, бо його захоплення триває до кінця запиту власника: воно відмовляло б такому коду в підключенні, яким власник у цей момент не користується, а так буває більшість часу. Чим обертається відмова — справа клієнта, як описано вище. phpredis завершує виклик невдачею, і власник зберігає свою відповідь. mysqlnd або відхиляє команду на підставі власного стану, або, коли обмін власника залишив цей стан готовим, отримує відмову в записі й закриває підключення, і запит власника завершується так, як описано в пункті 4. Тож деструктор — погане місце, щоб узагалі користуватися спільним клієнтом.

3. Деякі випадки навмисно не охоплено. Об’єкт запиту чи результату, збережений між запитами, перед яким не було захопленого виклику: PDOStatement::execute() на запиті, підготовленому в попередньому запиті, поводиться так, наче захоплення немає взагалі, і це коштує більше, ніж сам виклик: доходячи до сокета, поки будь-який файбер призупинений на підключенні, він отримує там відмову, а для mysqlnd відмова означає втрату підключення, як описано вище, — і на читанні, що отримує наступний рядок небуферизованого результату, і на записі, що надсилає команду. Протокол, написаний вручну на сирому сокеті (записати команду, призупинитися на чомусь іншому, прочитати відповідь пізніше), бо рівень сокета відхиляє лише тоді, коли власник призупинений на самій відповіді, а між цими двома точками підключення перехоплює інший файбер; три клієнти вище захищені тут своїм захопленням на рівні клієнта, якого протокол, написаний вручну, не має.

   Постійні підключення охоплено; див. Постійні підключення PDO нижче.

4. Закриття спільного підключення, поки інший запит призупинений на читанні з нього, завершує той запит із 500 і рядком у лозі, що пояснює, що сталося. Захоплення розводить два обміни; воно не може зберегти підключення живим, а відповідь призупиненого запиту — на підключенні, якого вже не існує, тож чесна відповідь — завершити його, а не повернути те, що тепер лежить у звільненій пам’яті. Які виклики можуть до цього призвести, залежить від клієнта, і чекає лише один із них: mysqli::close() і mysqli_close() — захоплені виклики, тож вони чекають на власника й закривають підключення, щойно це очікування вичерпано, тоді як Redis::close() теж захоплений, але кидає RedisException замість закриття. Усе інше закриває одразу — fclose() на сирому потоці і, що важливо, PDO, у якого взагалі немає методу close(): підключення звільняється, коли зникає останнє посилання на дескриптор (unset($pdo), повторне присвоєння або вихід з області видимості), а цей шлях виконується всередині власного демонтажу об’єктів рушія, де жодне захоплення не враховується перед закриттям підключення. Тож допоміжна функція перепідключення, що повторно присвоює спільний дескриптор PDO, завершує запити, призупинені на старому підключенні, без обмеженого очікування, яке отримує її еквівалент для mysqli. Запит дізнається про це одразу під час закриття, а не на власному дедлайні читання, яким для mysqlnd був би mysqlnd.net_read_timeout — за замовчуванням доба. Застосунки, що закривають спільне підключення, щоб примусово перепідключитися (звичайний приклад — $wpdb->check_connection() у WordPress), мають очікувати, що запити, призупинені на ньому в цей момент, завершаться помилкою, а не повернуть хибні дані.

Ще одна межа: хук streams під планувальником файберів у просторі користувача (AMPHP, Revolt) повертається до блокувального введення-виведення. Файбер, запущений таким планувальником, працює у власному контексті, який планувальник OxPHP не може відновити, тож хук це виявляє й іде нативним шляхом, а не псує жоден із планувальників. Ідеться про файбер, який планувальник у просторі користувача запускає всередині запиту. Власний файбер запиту — той, яким керує OxPHP, і в режимі воркерів це справжній Fiber (Fiber::getCurrent() усередині запиту повертає його), тож бібліотеки, яким потрібно лише розрізняти конкурентні запити, працюють без жодного запасного шляху. З тієї самої причини Revolt відмовляється запускати свій цикл подій зсередини запиту в режимі воркерів.

Постійні підключення PDO

PDO::ATTR_PERSISTENT тримає підключення драйвера в пулі, спільному для всього воркера, і PDO звертається до цього пулу у два кроки, які не витримують перемежовування: шукає підключення в пулі, перш ніж підключатися, і реєструє те, що створив, після цього. Два конструктори, що перекриваються, обидва не знаходять запису в пулі, і друга реєстрація замінює перший запис, закриваючи те підключення під тим запитом, що читає на ньому свою відповідь. Перекриття — звичайний випадок, бо до static $pdo ??= new PDO(...) доходить кожен запит, що надходить до завершення першого підключення.

Тому конструктори, що запитують постійне підключення до одного джерела даних, виконуються по одному на воркер, і другий знаходить те, що зареєстрував перший. Джерело даних — те, яке визначає PDO (псевдонім із pdo.dsn.* у php.ini рахується як DSN, який він називає), і конструктори до різних джерел, як правило, одне на одного не чекають, тож конструктор, що застряг, підключаючись до сервера, який приймає підключення й ніколи не відповідає, не затримує конструкторів до справного. Два випадки чекають більше, а не менше:

• DSN, однакові до двокрапки. DSN порівнюється лише до першої двокрапки після префікса драйвера (хост IPv6 — один зі способів її мати), бо PDO об’єднує DSN, користувача й пароль у свій ключ пулу через двокрапки й нічого не екранує, тож DSN, розширений :…, може називати той самий запис пулу, що й DSN без цього розширення. Джерела, однакові до цієї двокрапки, ділять одне очікування, включно із застряглим: два хости IPv6 з однаковою початковою групою цифр чекають одне на одного так, як раніше чекали всі конструктори на воркері.
• DSN uri: і DSN, що не є рядками. Їх неможливо визначити, не повторивши того, що з ними робить PDO, тож такий конструктор чекає, доки на його воркері не залишиться жодного постійного конструктора до будь-якого джерела даних, що виконується, а всі вони чекають, поки виконується він. Поки він чекає, він нічого не тримає, тож не затримує інших, але поки виконується конструктор до сервера, що ніколи не відповідає, він не може знайти такого моменту, і коли його очікування вичерпано, він продовжує без серіалізації. Тож випадок із застряглим сервером, описаний вище, усе ж зачіпає DSN uri: і об’єктні DSN, а той, що називає сам застряглий сервер, затримує кожен постійний конструктор на своєму воркері на весь час свого підключення, точно як раніше.

Це очікування обмежене так само, як описані вище, але те, чим воно обертається, коли вичерпане, — не помилка, яку кидає клієнт: конструктор, чий бюджет закінчився, продовжує без серіалізації й повідомляє про це в лозі сервера, а два конструктори, що так перекрилися, замінюють записи одне одного в пулі, як і раніше. Це завершує запит, що читає свою відповідь на заміненому підключенні, і, оскільки дескриптор із пулу звільняється незалежно від того, скільки об’єктів PDO ще на нього вказують, може завершити процес воркера, коли один із цих об’єктів згодом буде знищено. Усередині власного файбера планувальника в просторі користувача цей бюджет вичерпується одразу: такий контекст неможливо призупинити, тож конструктор, що виявляє інший конструктор у процесі, здається негайно.

Інший крок — перевірка живучості, яку PDO робить, перш ніж віддати підключення з пулу: ping на самому підключенні. Надісланий, поки власник призупинений в очікуванні своєї відповіді, він отримав би відмову, PDO вважав би підключення мертвим і відкрив би друге, і те, що застосунок мав намір розділити, вже не було б спільним. Тож підключення, яке тримає інший файбер, повідомляється живим без ping, але лише конструкторові, який залишив би його точно таким, як є (коли драйвер не надає перевірки живучості, як-от pdo_sqlite, та сама відповідь заміняє власну перевірку PDO). PDO записує режим помилок, прапорець автокоміту й інші свої параметри на дескриптор із пулу, який віддає, і на підключенні, що використовується, ці записи лягли б на власника. Тому підключення стає спільним лише з конструктором, який не записав би на нього нічого нового:

• кожен параметр, який він передає, — один із тих, що PDO зберігає на самому дескрипторі (PDO::ATTR_ERRMODE, PDO::ATTR_CASE, PDO::ATTR_ORACLE_NULLS, PDO::ATTR_DEFAULT_FETCH_MODE; запис PDO::ATTR_PERSISTENT, що називає пул, не рахується), і
• кожен має те значення, яке вже має підключення.

Параметр, про який треба повідомити драйвер, відхиляється незалежно від значення — включно з PDO::ATTR_AUTOCOMMIT і PDO::ATTR_STRINGIFY_FETCHES — на кожному драйвері, зокрема сторонніх. Конструкторові, що не відповідає будь-якій із цих умов, повідомляють, що підключення мертве, і він отримує власне, а лог сервера каже про це щонайбільше раз на секунду. Для ключа пулу, чиї параметри містять PDO::ATTR_EMULATE_PREPARES або PDO::ATTR_STRINGIFY_FETCHES, як у Laravel, це означає: спільне між запитами й між файберами, що виконують конструктор до запиту до бази, але конструктор, що надходить, поки інший запит тримає підключення, відкриває власне. Захоплення триває від першого запиту власника до бази до кінця його запиту.

Підключення, яким ніхто не користується, перевіряється як і раніше, включно з тим, чий власник позбувся останнього дескриптора, тож справді мертве підключення все одно замінюється. Ця перевірка — така сама команда, як і будь-яка інша, і захоплюється так само: запит до бази, що надходить через захищеного клієнта, поки вона виконується, чекає на неї у звичайних межах. Непокриті випадки, описані вище, лишаються непокритими й тут.

Увімкнення й вартість

1, true і all вмикають усі категорії, включно зі streams і net. Тож розгортання, що вже задає RUNTIME_HOOKS=1 заради хуків sleep, після оновлення почне перехоплювати сокети без жодної власної правки; перелічіть категорії явно (RUNTIME_HOOKS=sleep або RUNTIME_HOOKS=sleep,streams, щоб зберегти те, що вмикала 0.12.0), якщо вам потрібно не це. Увімкнення streams також патчить на старті один запис таблиці операцій потоків PHP у пам’яті; сторінку повертають у той стан, у якому її знайшли, але на платформі, де її початковий захист визначити неможливо, вона лишається доступною для запису — невелика втрата захищеності, про яку повідомляє лог сервера. Увімкнення net на тих самих умовах патчить такі самі записи в таблицях операцій інших транспортів сокетів і OpenSSL і змушує бібліотеку-міст відповідати на poll() для викликів, які робить власний код PHP; кожен інший викликач, включно з власним кодом сервера, передається напряму до libc.

Вартість, виміряна: близько 3–5 мкс на кожен цикл обміну із сокетом на воркері, де більше нічого не призупинено, близько 5–6 мкс із 64 файберами, призупиненими на дескрипторах, і близько 7–11 мкс із 200. Готовність визначається через набір, який ядро зберігає між очікуваннями, тож ця цифра залежить від того, скільки дескрипторів стали готовими, а не від того, скільки їх чекає. Неактивний воркер чекає на ці дескриптори, а не спить фіксований інтервал, помічаючи готовність лише на наступному такті, і це дуже важливо: сліпий сон коштував натомість приблизно 2 мс на цикл обміну.

Широкий stream_select() має накладні витрати, яких немає у вузькому випадку, бо кожен дескриптор, названий у виклику, реєструється перед очікуванням і знімається після нього. Виміряні без самого очікування — кожен дескриптор уже готовий до читання, тож виклик повертається одразу й лишаються тільки накладні витрати, — вони становлять близько 6 мкс проти 5 мкс без хука для одного дескриптора, 56 мкс проти 9 мкс для 64 і 130–150 мкс проти 16–21 мкс для 200: приблизно 0,65 мкс на дескриптор.

Сприймайте це як фіксовану вартість виклику, а не як сповільнення тієї самої роботи. stream_select(), що справді чекає, — а саме для цього пишуть цикл select, — її затьмарює: мілісекунда очікування робить навіть цифру для 200 дескрипторів приблизно десятою частиною виклику, а купує вона потік воркера, який неперехоплений виклик тримає все очікування. Винятком є дві форми, і для них категорію краще залишити вимкненою: виклик на багатьох дескрипторах, який майже ніколи не чекає, бо тут немає часу потоку, який можна повернути; і запит, який сам є циклом подій, де потокові й так більше нічого виконувати. Клієнти, що чекають на одному підключенні, — mysqlnd, phpredis, обгортки потоків HTTP, — перебувають на верхньому рядку таблиці, де накладні витрати становлять близько мікросекунди.

RUNTIME_HOOKS проти oxphp_sleep()

Хук не замінює власний примітив OxPHP — вони охоплюють різні випадки:

• Використовуйте oxphp_sleep() / oxphp_usleep() у коді, який пишете ви. Вони призупиняють файбер у режимі воркерів без жодного прапорця середовища, а oxphp_sleep() приймає дробові секунди (oxphp_sleep(0.25)) — точність, якої нативний sleep() (цілі секунди) виразити не може. На них теж поширюються місця, де файбер не може призупинитися: там вони тримають потік воркера точно так, як перехоплені вбудовані функції.
• Увімкніть RUNTIME_HOOKS=sleep для коду, який ви не можете редагувати, — наприклад, фреймворку чи сторонньої бібліотеки, що напряму викликає нативні sleep()/usleep(). Він вимкнений за замовчуванням, нічого не робить поза файбером і зберігає нативний контракт повернення: перехоплений sleep(), як і раніше, приймає int, повертає 0, коли призупиняється, і те, що повертає вбудована функція, коли переходить до запасного шляху. Перевірка аргументу — його власна, як описано вище.

Якщо покладатися на RUNTIME_HOOKS у власних обробниках, їхня кооперативність залежатиме від налаштування розгортання, а не від коду; там віддавайте перевагу явному oxphp_sleep().

Спільний стан

Примітиви конкурентності в межах процесу (OxPHP\Shared\Counter, Map, Channel, Mutex, Once, Pool, Atomic, Flag, Registry). Огляд API див. у розділі Спільний стан.

Профілювання

Семплювальний профілювальник, що видає трейси у форматах xhprof / speedscope. Формати виводу й інтеграцію з переглядачами див. у розділі Профілювання.

Приклади конфігурацій

Розробка

Продакшн (Framework)

Продакшн (режим воркерів)

TLS

Перегляд чинної конфігурації

Коли внутрішній сервер працює, зверніться до ендпоінту /config, щоб побачити розв’язану конфігурацію:

Промпти для вашого агента

Ці промпти розраховані на агента з підключеним MCP-сервером документації OxPHP — потрібні сторінки він прочитає сам.

Див. також

• Маршрутизація — режими маршрутизації й поведінка ENTRY_FILE
• Health-перевірки — ендпоінти внутрішнього сервера
• Метрики — довідник Prometheus-сумісних метрик
• Коректне завершення роботи — як DRAIN_TIMEOUT_SECONDS впливає на завершення
• TLS — налаштування TLS і вимоги до сертифікатів
• Обмеження частоти запитів — подробиці обмеження частоти для кожного IP
• Режим воркерів — архітектура постійних PHP-воркерів
• Стиснення — вибір кодека й рівні для кожного кодування
• Статичні файли — кешування й віддача файлів
• Розподілене трасування та APM — експорт OTel, автоматичне інструментування й PHP SDK для трасування