You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Acts as a precontent phase handler and executes Lua code string specified in `{ <lua-script }` for every request.
1858
+
The Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox).
1859
+
1860
+
Note that this handler always runs *after* the standard [ngx_http_mirror_module](https://nginx.org/en/docs/http/ngx_http_mirror_module.html) and [ngx_http_try_files_module](https://nginx.org/en/docs/http/ngx_http_core_module.html#try_files). For example:
1861
+
1862
+
```nginx
1863
+
location /images/ {
1864
+
try_files $uri /images/default.gif;
1865
+
precontent_by_lua_block {
1866
+
ngx.log(ngx.NOTICE, "file found")
1867
+
}
1868
+
}
1869
+
1870
+
location = /images/default.gif {
1871
+
expires 30s;
1872
+
precontent_by_lua_block {
1873
+
ngx.log(ngx.NOTICE, "file not found, use default.gif instead")
1874
+
}
1875
+
}
1876
+
```
1877
+
1878
+
That is, if a request for /images/foo.jpg comes in and the file does not exist, the request will be internally redirected to /images/default.gif before [precontent_by_lua_block](#precontent_by_lua_block), and then the [precontent_by_lua_block](#precontent_by_lua_block) in new location will run and log "file not found, use default.gif instead".
1879
+
1880
+
You can use [precontent_by_lua_block](#precontent_by_lua_block) to perform some preparatory functions after the access phase handler but before the proxy or other content handler. Especially some functions that cannot be performed in [balancer_by_lua_block](#balancer_by_lua_block).
1881
+
1882
+
you can use the [precontent_by_lua_no_postpone](#precontent_by_lua_no_postpone) directive to control when to run this handler inside the "precontent" request-processing phase
Equivalent to [precontent_by_lua_block](#precontent_by_lua_block), except that the file specified by `<path-to-lua-script-file>` contains the Lua code, or, as from the `v0.5.0rc32` release, the [LuaJIT bytecode](#luajit-bytecode-support) to be executed.
1897
+
1898
+
Nginx variables can be used in the `<path-to-lua-script-file>` string to provide flexibility. This however carries some risks and is not ordinarily recommended.
1899
+
1900
+
When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
1901
+
1902
+
When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached
1903
+
and the Nginx config must be reloaded each time the Lua source file is modified.
1904
+
The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache)`off` in `nginx.conf` to avoid repeatedly reloading Nginx.
1905
+
1906
+
Nginx variables are supported in the file path for dynamic dispatch just as in [content_by_lua_file](#content_by_lua_file).
1907
+
1908
+
But be very careful about malicious user inputs and always carefully validate or filter out the user-supplied path components.
1909
+
1910
+
[Back to TOC](#directives)
1911
+
1845
1912
content_by_lua
1846
1913
--------------
1847
1914
@@ -2710,7 +2777,7 @@ directive.
2710
2777
This Lua code execution context does not support yielding, so Lua APIs that may yield
2711
2778
(like cosockets and "light threads") are disabled in this context. One can usually work
2712
2779
around this limitation by doing such operations in an earlier phase handler (like
2713
-
[access_by_lua*](#access_by_lua)) and passing along the result into this context
2780
+
[precontent_by_lua*](#precontent_by_lua_block)) and passing along the result into this context
2714
2781
via the [ngx.ctx](#ngxctx) table.
2715
2782
2716
2783
This directive was first introduced in the `v0.10.0` release.
@@ -3647,6 +3714,19 @@ This directive was first introduced in the `v0.9.20` release.
3647
3714
3648
3715
[Back to TOC](#directives)
3649
3716
3717
+
precontent_by_lua_no_postpone
3718
+
-------------------------
3719
+
3720
+
**syntax:***precontent_by_lua_no_postpone on|off*
3721
+
3722
+
**default:***precontent_by_lua_no_postpone off*
3723
+
3724
+
**context:***http*
3725
+
3726
+
Controls whether or not to disable postponing [precontent_by_lua*](#precontent_by_lua_block) directives to run at the end of the `precontent` request-processing phase. By default, this directive is turned off and the Lua code is postponed to run at the end of the `precontent` phase.
Acts as a precontent phase handler and executes Lua code string specified in <code>{ <lua-script }</code> for every request.
1503
+
The Lua code may make [[#Nginx API for Lua|API calls]] and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox).
1504
+
1505
+
Note that this handler always runs *after* the standard [[HttpMirrorModule]] and [[HttpTryFilesModule]]. For example:
1506
+
1507
+
<geshi lang="nginx">
1508
+
location /images/ {
1509
+
try_files $uri /images/default.gif;
1510
+
precontent_by_lua_block {
1511
+
ngx.log(ngx.NOTICE, "file found")
1512
+
}
1513
+
}
1514
+
1515
+
location = /images/default.gif {
1516
+
expires 30s;
1517
+
precontent_by_lua_block {
1518
+
ngx.log(ngx.NOTICE, "file not found, use default.gif instead")
1519
+
}
1520
+
}
1521
+
</geshi>
1522
+
1523
+
That is, if a request for /images/foo.jpg comes in and the file does not exist, the request will be internally redirected to /images/default.gif before [[#precontent_by_lua_block|precontent_by_lua_block]], and then the [[#precontent_by_lua_block|precontent_by_lua_block]] in new location will run and log "file not found, use default.gif instead".
1524
+
1525
+
You can use [[#precontent_by_lua_block|precontent_by_lua_block]] to perform some preparatory functions after the access phase handler but before the proxy or other content handler. Especially some functions that cannot be performed in [[#balancer_by_lua_block|balancer_by_lua_block]].
1526
+
1527
+
You can use the [[#precontent_by_lua_no_postpone|precontent_by_lua_no_postpone]] directive to control when to run this handler inside the "precontent" request-processing phase of Nginx.
Equivalent to [[#precontent_by_lua_block|precontent_by_lua_block]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code, or, as from the <code>v0.5.0rc32</code> release, the [[#LuaJIT bytecode support|LuaJIT bytecode]] to be executed.
1538
+
1539
+
Nginx variables can be used in the <code><path-to-lua-script-file></code> string to provide flexibility. This however carries some risks and is not ordinarily recommended.
1540
+
1541
+
When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
1542
+
1543
+
When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached
1544
+
and the Nginx config must be reloaded each time the Lua source file is modified.
1545
+
The Lua code cache can be temporarily disabled during development by switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid repeatedly reloading Nginx.
1546
+
1547
+
Nginx variables are supported in the file path for dynamic dispatch just as in [[#content_by_lua_file|content_by_lua_file]].
1548
+
1494
1549
== content_by_lua ==
1495
1550
1496
1551
'''syntax:''' ''content_by_lua <lua-script-str>''
@@ -3017,6 +3072,16 @@ Controls whether or not to disable postponing [[#access_by_lua|access_by_lua*]]
3017
3072
3018
3073
This directive was first introduced in the <code>v0.9.20</code> release.
Controls whether or not to disable postponing [[#precontent_by_lua_block|precontent_by_lua_block*]] directives to run at the end of the <code>precontent</code> request-processing phase. By default, this directive is turned off and the Lua code is postponed to run at the end of the <code>precontent</code> phase.
0 commit comments