Skip to content

Commit 04cf628

Browse files
leonardolaraleonardolara
committed
initial translation of reference/luasandbox
1 parent 2788867 commit 04cf628

34 files changed

+3081
-0
lines changed

‎reference/luasandbox/book.xml

+86
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 46a9cdd2dbef4ec89bf65fad9930e2feb78bbb98 Maintainer: leonardolara Status: ready -->
3+
4+
<book xml:id="book.luasandbox" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
<?phpdoc extension-membership="pecl" ?>
6+
<title>LuaSandbox</title>
7+
<titleabbrev>LuaSandbox</titleabbrev>
8+
9+
<preface xml:id="intro.luasandbox">
10+
&reftitle.intro;
11+
<para>
12+
LuaSandbox é uma extensão para PHP 7 e PHP 8 para permitir a execução
13+
segura de código Lua 5.1 não confiável de dentro do PHP.
14+
</para>
15+
<para>
16+
Diferenças em comparação com a extensão <link linkend="book.lua">Lua</link>:
17+
<itemizedlist>
18+
<listitem>
19+
<para>
20+
O LuaSandbox tem suporte para limites de tempo e memória.
21+
</para>
22+
</listitem>
23+
<listitem>
24+
<para>
25+
LuaSandbox fornece um ambiente seguro padrão para executar código não confiável.
26+
As funções do Lua Stock foram revisadas para segurança, e várias foram corrigidas
27+
de acordo.
28+
</para>
29+
</listitem>
30+
<listitem>
31+
<para>
32+
LuaSandbox tem uma interface PHP que é mais complexa, precisa e poderosa,
33+
mas é menos conveniente para desenvolvedores.
34+
</para>
35+
</listitem>
36+
<listitem>
37+
<para>
38+
LuaSandbox suporta apenas Lua 5.1. É difícil mudar isso, porque
39+
LuaSandbox usa bibliotecas padrão Lua bastante modificadas, e
40+
devido à falta de compatibilidade com versões anteriores entre as principais versões Lua.
41+
LuaSandbox visa maximizar a compatibilidade com versões anteriores com scripts
42+
fornecidos pelo usuário.
43+
</para>
44+
</listitem>
45+
</itemizedlist>
46+
</para>
47+
</preface>
48+
49+
&reference.luasandbox.setup;
50+
&reference.luasandbox.differences;
51+
&reference.luasandbox.examples;
52+
53+
<!-- &reference.luasandbox.reference; -->
54+
55+
&reference.luasandbox.luasandbox;
56+
&reference.luasandbox.luasandboxfunction;
57+
&reference.luasandbox.luasandboxerror;
58+
&reference.luasandbox.luasandboxerrorerror;
59+
&reference.luasandbox.luasandboxfatalerror;
60+
&reference.luasandbox.luasandboxmemoryerror;
61+
&reference.luasandbox.luasandboxruntimeerror;
62+
&reference.luasandbox.luasandboxsyntaxerror;
63+
&reference.luasandbox.luasandboxtimeouterror;
64+
65+
</book>
66+
67+
<!-- Keep this comment at the end of the file
68+
Local variables:
69+
mode: sgml
70+
sgml-omittag:t
71+
sgml-shorttag:t
72+
sgml-minimize-attributes:nil
73+
sgml-always-quote-attributes:t
74+
sgml-indent-step:1
75+
sgml-indent-data:t
76+
indent-tabs-mode:nil
77+
sgml-parent-document:nil
78+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
79+
sgml-exposed-tags:nil
80+
sgml-local-catalogs:nil
81+
sgml-local-ecat-files:nil
82+
End:
83+
vim600: syn=xml fen fdm=syntax fdl=2 si
84+
vim: et tw=78 syn=sgml
85+
vi: ts=1 sw=1
86+
-->

‎reference/luasandbox/configure.xml

+34
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 990521c9ca64fe7d83016a613b850177d3a90776 Maintainer: leonardolara Status: ready -->
3+
4+
<section xml:id="luasandbox.installation" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
&reftitle.install;
6+
7+
<para>
8+
&pecl.info;
9+
<link xlink:href="&url.pecl.package;luasandbox">&url.pecl.package;luasandbox</link>
10+
</para>
11+
12+
</section>
13+
14+
15+
<!-- Keep this comment at the end of the file
16+
Local variables:
17+
mode: sgml
18+
sgml-omittag:t
19+
sgml-shorttag:t
20+
sgml-minimize-attributes:nil
21+
sgml-always-quote-attributes:t
22+
sgml-indent-step:1
23+
sgml-indent-data:t
24+
indent-tabs-mode:nil
25+
sgml-parent-document:nil
26+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
27+
sgml-exposed-tags:nil
28+
sgml-local-catalogs:nil
29+
sgml-local-ecat-files:nil
30+
End:
31+
vim600: syn=xml fen fdm=syntax fdl=2 si
32+
vim: et tw=78 syn=sgml
33+
vi: ts=1 sw=1
34+
-->

‎reference/luasandbox/differences.xml

+130
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 990521c9ca64fe7d83016a613b850177d3a90776 Maintainer: leonardolara Status: ready -->
3+
<chapter xml:id="reference.luasandbox.differences" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<title>Diferenças do Lua Padrão</title>
5+
6+
<para>
7+
O LuaSandbox fornece um ambiente isolado (caixa de areia) que difere em alguns aspectos do Lua 5.1 padrão.
8+
</para>
9+
10+
<simplesect xml:id="reference.luasandbox.differences.unavailable">
11+
<title>Recursos que não estão disponíveis</title>
12+
<para>
13+
<itemizedlist>
14+
<listitem>
15+
<para>
16+
<literal>dofile()</literal>, <literal>loadfile()</literal> e o pacote <literal>io</literal>, pois eles permitem acesso direto ao sistema de arquivos. Se necessário, o acesso ao sistema de arquivos deve ser feito por meio de funções de retorno PHP.
17+
</para>
18+
</listitem>
19+
<listitem>
20+
<para>
21+
O pacote <literal>package</literal>, incluindo <literal>require()</literal> e <literal>module()</literal>, pois depende muito do acesso direto ao sistema de arquivos. Uma reescrita Lua pura, como a usada na extensão MediaWiki Scribunto, pode ser usada em vez disso.
22+
</para>
23+
</listitem>
24+
<listitem>
25+
<para>
26+
<literal>load()</literal> e <literal>loadstring()</literal>, para permitir análise estática do código Lua.
27+
</para>
28+
</listitem>
29+
<listitem>
30+
<para>
31+
<literal>print()</literal>, já que ele envia para a saída padrão. Se necessário, a saída deve ser feita via funções de retorno PHP.
32+
</para>
33+
</listitem>
34+
<listitem>
35+
<para>
36+
A maior parte do pacote <literal>os</literal>, pois permite a manipulação do processo e a execução de outros processos.
37+
</para>
38+
<para>
39+
<itemizedlist>
40+
<listitem>
41+
<para>
42+
<literal>os.clock()</literal>, <literal>os.date()</literal>, <literal>os.difftime()</literal> e <literal>os.time()</literal> permanecem disponíveis.
43+
</para>
44+
</listitem>
45+
</itemizedlist>
46+
</para>
47+
</listitem>
48+
<listitem>
49+
<para>
50+
A maior parte do pacote <literal>debug</literal>, pois permite a manipulação do estado Lua e metadados de maneiras que podem quebrar o isolamento.
51+
</para>
52+
<para>
53+
<itemizedlist>
54+
<listitem>
55+
<para>
56+
<literal>debug.traceback()</literal> permanece disponível.
57+
</para>
58+
</listitem>
59+
</itemizedlist>
60+
</para>
61+
</listitem>
62+
<listitem>
63+
<para>
64+
<literal>string.dump()</literal>, pois pode expor dados internos.
65+
</para>
66+
</listitem>
67+
<listitem>
68+
<para>
69+
<literal>collectgarbage()</literal>, <literal>gcinfo()</literal> e o pacote <literal>coroutine</literal> não foram revisados ​​quanto à segurança.
70+
</para>
71+
</listitem>
72+
</itemizedlist>
73+
</para>
74+
</simplesect>
75+
76+
<simplesect xml:id="reference.luasandbox.differences.modified">
77+
<title>Recursos que foram modificados</title>
78+
<para>
79+
<itemizedlist>
80+
<listitem>
81+
<para>
82+
<literal>pcall()</literal> e <literal>xpcall()</literal> não conseguem capturar certos erros, particularmente erros de tempo limite.
83+
</para>
84+
</listitem>
85+
<listitem>
86+
<para>
87+
<literal>tostring()</literal> não inclui endereços de ponteiros.
88+
</para>
89+
</listitem>
90+
<listitem>
91+
<para>
92+
<literal>string.match()</literal> foi corrigido para limitar a profundidade da recursão e verificar periodicamente se há um tempo limite.
93+
</para>
94+
</listitem>
95+
<listitem>
96+
<para>
97+
<literal>math.random()</literal> e <literal>math.randomseed()</literal> foram substituídos por versões que não compartilham estado com <literal>rand()</literal> do PHP.
98+
</para>
99+
</listitem>
100+
<listitem>
101+
<para>
102+
Os metamétodos <literal>__pairs</literal> e <literal>__ipairs</literal> do Lua 5.2 são suportados por <literal>pairs()</literal> e <literal>ipairs()</literal>.
103+
</para>
104+
</listitem>
105+
</itemizedlist>
106+
</para>
107+
</simplesect>
108+
109+
</chapter>
110+
111+
<!-- Keep this comment at the end of the file
112+
Local variables:
113+
mode: sgml
114+
sgml-omittag:t
115+
sgml-shorttag:t
116+
sgml-minimize-attributes:nil
117+
sgml-always-quote-attributes:t
118+
sgml-indent-step:1
119+
sgml-indent-data:t
120+
indent-tabs-mode:nil
121+
sgml-parent-document:nil
122+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
123+
sgml-exposed-tags:nil
124+
sgml-local-catalogs:nil
125+
sgml-local-ecat-files:nil
126+
End:
127+
vim600: syn=xml fen fdm=syntax fdl=2 si
128+
vim: et tw=78 syn=sgml
129+
vi: ts=1 sw=1
130+
-->

‎reference/luasandbox/examples.xml

+89
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<!-- EN-Revision: 990521c9ca64fe7d83016a613b850177d3a90776 Maintainer: leonardolara Status: ready -->
3+
4+
<chapter xml:id="luasandbox.examples" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
5+
&reftitle.examples;
6+
7+
<!-- Add one or more of these <section>'s, with one ore more <example>'s -->
8+
<!-- Make sure each xml:id is unique -->
9+
<section xml:id="luasandbox.examples-basic">
10+
<title>Uso básico para LuaSandbox</title>
11+
<para>
12+
Depois de compilado o PHP com suporte ao LuaSandbox, pode-se começar a usar o LuaSandbox para executar com segurança o código Lua fornecido pelo usuário.
13+
</para>
14+
<para>
15+
<example>
16+
<title>Executando um código Lua</title>
17+
<programlisting role="php" xml:id="luasandbox.examples.uniqueidhere">
18+
<![CDATA[
19+
<?php
20+
21+
$sandbox = new LuaSandbox;
22+
$sandbox->setMemoryLimit( 50 * 1024 * 1024 );
23+
$sandbox->setCPULimit( 10 );
24+
25+
// Registra algumas funções no ambiente Lua
26+
27+
function frobnosticate( $v ) {
28+
return [ $v + 42 ];
29+
}
30+
31+
$sandbox->registerLibrary( 'php', [
32+
'frobnosticate' => 'frobnosticate',
33+
'output' => function ( $string ) {
34+
echo "$string\n";
35+
},
36+
'error' => function () {
37+
throw new LuaSandboxRuntimeError( "Algo está errado" );
38+
}
39+
] );
40+
41+
// Executa algum código Lua, incluindo funções de retorno em PHP e em Lua
42+
43+
$luaCode = <<<EOF
44+
php.output( "Olá, mundo" );
45+
46+
return "Oi", function ( v )
47+
return php.frobnosticate( v + 200 )
48+
end
49+
EOF;
50+
51+
list( $hi, $frob ) = $sandbox->loadString( $luaCode )->call();
52+
assert( $frob->call( 4000 ) === [ 4242 ] );
53+
54+
// Exceções LuaSandboxRuntimeError geradas pelo PHP podem ser capturadas dentro do Lua
55+
56+
list( $ok, $message ) = $sandbox->loadString( 'return pcall( php.error )' )->call();
57+
assert( !$ok );
58+
assert( $message === 'Algo está errado' );
59+
60+
?>
61+
]]>
62+
</programlisting>
63+
</example>
64+
</para>
65+
</section>
66+
67+
</chapter>
68+
69+
<!-- Keep this comment at the end of the file
70+
Local variables:
71+
mode: sgml
72+
sgml-omittag:t
73+
sgml-shorttag:t
74+
sgml-minimize-attributes:nil
75+
sgml-always-quote-attributes:t
76+
sgml-indent-step:1
77+
sgml-indent-data:t
78+
indent-tabs-mode:nil
79+
sgml-parent-document:nil
80+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
81+
sgml-exposed-tags:nil
82+
sgml-local-catalogs:nil
83+
sgml-local-ecat-files:nil
84+
End:
85+
vim600: syn=xml fen fdm=syntax fdl=2 si
86+
vim: et tw=78 syn=sgml
87+
vi: ts=1 sw=1
88+
-->
89+

0 commit comments

Comments
 (0)