Skip to content

Commit 7291bd6

Browse files
mamodmamod
committed
update docs
1 parent fbde061 commit 7291bd6

File tree

2 files changed

+280
-10
lines changed

2 files changed

+280
-10
lines changed

‎README.pod‎

Lines changed: 140 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -9,28 +9,67 @@ JavaScript::Duktape - Perl interface to Duktape embeddable javascript engine
99

1010
use JavaScript::Duktape;
1111

12-
##create new js context
12+
## create new js context
1313
my $js = JavaScript::Duktape->new();
1414

15-
#set function to be used from javascript land
15+
# set function to be used from javascript land
1616
$js->set('write' => sub {
1717
print $_[0], "\n";
1818
});
1919

20-
$js->eval(qq~
20+
$js->eval(qq{
2121
(function(){
2222
for (var i = 0; i < 100; i++){
2323
write(i);
2424
}
2525
})();
26-
~);
26+
});
2727

2828
=head1 DESCRIPTION
2929

3030
JavaScript::Duktape implements almost all duktape javascript engine api, the c code is just
3131
a thin layer that maps duktape api to perl, and all other functions implemented in perl
3232
it self, so maintaing and contributing to the base code should be easy.
3333

34+
=head1 JavaScript::Duktape->new(%options)
35+
36+
initiate JavaScript::Duktape with options
37+
38+
=head2 options
39+
40+
=over 4
41+
42+
=item max_memory
43+
44+
Set maximum memory allowed for the excuted javascript code to consume, not setting
45+
this option is the default, which means no restricts on the maximum memory that can
46+
be consumed.
47+
48+
Minumum value to set for the C<max_memory> option is 256 * 1024 = (256k)
49+
setting number below 256k will croak.
50+
51+
max_memory => 256 * 1024 * 2
52+
53+
You can resize the memory allowed to consume on different executions by calling
54+
C<resize_memory> method, see L<Sandboxing> section below.
55+
56+
=item timout
57+
58+
Set maximum time javascript code can run, this value represented in seconds and is not 100% guranteed
59+
that the javascript code will fail after the exact value passed, but it will eventually fail on first tick checking.
60+
61+
Not setting this option is the default, which means no timeout checking at all
62+
63+
timeout => 5
64+
65+
You can override this value later on another code evaluation by calling C<set_timeout> method
66+
67+
$js->set_timeout(25);
68+
69+
See L<Sandboxing> section below
70+
71+
=back
72+
3473
=head1 methods
3574

3675
=over 4
@@ -97,6 +136,93 @@ examples provided with this distribution
97136

98137
=back
99138

139+
=head1 Sandboxing
140+
141+
As of version C<2.2.0> C<JavaScript::Duktape> integrated some of
142+
Duktape Engine Sandboxing methods, this will allow developers to restrict
143+
the running javascript code by restricting memory consumption and running time
144+
145+
C<DUK_USE_EXEC_TIMEOUT_CHECK> flag is set by default to enable
146+
L<< Bytecode execution timeout|https://github.com/svaarala/duktape/blob/master/doc/sandboxing.rst#bytecode-execution-timeout-details >>
147+
148+
# prevent javascript code to consume memory more
149+
# than max_memory option
150+
151+
my $js = JavaScript::Duktape->new( max_memory => 256 * 1024 );
152+
153+
# this will fail with "Error: alloc failed" message
154+
# when running, because it will consume more memory
155+
# than the allowed max_memory
156+
$js->eval(q{
157+
var str = '';
158+
while(1){ str += 'XXXX' }
159+
});
160+
161+
=head2 C<set_timout(t)>
162+
163+
Enable/Disable timeout checking, to disable set the value to 0
164+
this value is in seconds
165+
166+
my $js = JavaScript::Duktape->new();
167+
168+
# throw 'time out' Error if executed
169+
# js code does not finish after 5 seconds
170+
$js->set_timeout(5);
171+
172+
eval {
173+
$js->eval(q{
174+
while(1){}
175+
});
176+
};
177+
178+
print $@, "\n"; #RangeError: execution timeout
179+
180+
# disable timeout checking
181+
$js->set_timeout(0);
182+
183+
# now will run infinitely
184+
$js->eval(q{
185+
while(1){}
186+
});
187+
188+
This method can be used with duktape VM instance too
189+
190+
my $js = JavaScript::Duktape->new();
191+
my $duk = $js->duk();
192+
193+
$duk->set_timeout(3);
194+
$duk->peva_stringl(q{
195+
while (1){}
196+
});
197+
198+
print $duk->safe_to_string(-1); # Error: execution 'time out'
199+
200+
=head2 C<resize_memory(m)>
201+
202+
This method will have effect only if you intiated with max_memory option
203+
204+
my $js = JavaScript::Duktape->new( max_memory => 1024 * 256 );
205+
206+
207+
eval {
208+
$js->eval(q{
209+
var buf = Buffer(( 1024 * 256 ) + 1000 );
210+
print('does not reach');
211+
});
212+
};
213+
214+
print $@, "\n"; # Error: 'alloc failed'
215+
216+
$js->resize_memory( 1024 * 256 * 2 );
217+
218+
# now it will not throw
219+
$js->eval(q{
220+
var buf = Buffer(( 1024 * 256 ) + 1000 );
221+
print('ok');
222+
});
223+
224+
225+
100226
=head1 VM API
101227

102228
vm api corresponds to Duktape Engine API see L<http://duktape.org/api.html>
@@ -327,16 +453,25 @@ Mamod Mehyar C<< <[email protected]> >>
327453

328454
=head1 CONTRIBUTORS
329455

330-
Big thanks for the much appreciated contributors
456+
Thanks for everyone who contributed to this module, either by code, bug reports, API design
457+
or suggestions
331458

332459
=over 4
333460

334461
=item * Rodrigo de Oliveira L<@rodrigolive|https://github.com/rodrigolive>
335462

336463
=item * jomo666 L<@jomo666|https://github.com/jomo666>
337464

465+
=item * Viacheslav Tykhanovskyi L<@vti|https://github.com/vti>
466+
467+
=item * Slaven Rezić L<@eserte|https://github.com/eserte>
468+
338469
=back
339470

471+
=head1 APPRECIATION
472+
473+
Credits should go to L<< Duktape Javascript embeddable engine|http://duktape.org >> and it's creator L<< Sami Vaarala|https://github.com/svaarala >>
474+
340475
=head1 LICENSE
341476

342477
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

‎lib/JavaScript/Duktape.pm‎

Lines changed: 140 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -991,28 +991,67 @@ JavaScript::Duktape - Perl interface to Duktape embeddable javascript engine
991991
992992
use JavaScript::Duktape;
993993
994-
##create new js context
994+
## create new js context
995995
my $js = JavaScript::Duktape->new();
996996
997-
#set function to be used from javascript land
997+
# set function to be used from javascript land
998998
$js->set('write' => sub {
999999
print $_[0], "\n";
10001000
});
10011001
1002-
$js->eval(qq~
1002+
$js->eval(qq{
10031003
(function(){
10041004
for (var i = 0; i < 100; i++){
10051005
write(i);
10061006
}
10071007
})();
1008-
~);
1008+
});
10091009
10101010
=head1 DESCRIPTION
10111011
10121012
JavaScript::Duktape implements almost all duktape javascript engine api, the c code is just
10131013
a thin layer that maps duktape api to perl, and all other functions implemented in perl
10141014
it self, so maintaing and contributing to the base code should be easy.
10151015
1016+
=head1 JavaScript::Duktape->new(%options)
1017+
1018+
initiate JavaScript::Duktape with options
1019+
1020+
=head2 options
1021+
1022+
=over 4
1023+
1024+
=item max_memory
1025+
1026+
Set maximum memory allowed for the excuted javascript code to consume, not setting
1027+
this option is the default, which means no restricts on the maximum memory that can
1028+
be consumed.
1029+
1030+
Minumum value to set for the C<max_memory> option is 256 * 1024 = (256k)
1031+
setting number below 256k will croak.
1032+
1033+
max_memory => 256 * 1024 * 2
1034+
1035+
You can resize the memory allowed to consume on different executions by calling
1036+
C<resize_memory> method, see L<Sandboxing> section below.
1037+
1038+
=item timout
1039+
1040+
Set maximum time javascript code can run, this value represented in seconds and is not 100% guranteed
1041+
that the javascript code will fail after the exact value passed, but it will eventually fail on first tick checking.
1042+
1043+
Not setting this option is the default, which means no timeout checking at all
1044+
1045+
timeout => 5
1046+
1047+
You can override this value later on another code evaluation by calling C<set_timeout> method
1048+
1049+
$js->set_timeout(25);
1050+
1051+
See L<Sandboxing> section below
1052+
1053+
=back
1054+
10161055
=head1 methods
10171056
10181057
=over 4
@@ -1079,6 +1118,93 @@ examples provided with this distribution
10791118
10801119
=back
10811120
1121+
=head1 Sandboxing
1122+
1123+
As of version C<2.2.0> C<JavaScript::Duktape> integrated some of
1124+
Duktape Engine Sandboxing methods, this will allow developers to restrict
1125+
the running javascript code by restricting memory consumption and running time
1126+
1127+
C<DUK_USE_EXEC_TIMEOUT_CHECK> flag is set by default to enable
1128+
L<< Bytecode execution timeout|https://github.com/svaarala/duktape/blob/master/doc/sandboxing.rst#bytecode-execution-timeout-details >>
1129+
1130+
# prevent javascript code to consume memory more
1131+
# than max_memory option
1132+
1133+
my $js = JavaScript::Duktape->new( max_memory => 256 * 1024 );
1134+
1135+
# this will fail with "Error: alloc failed" message
1136+
# when running, because it will consume more memory
1137+
# than the allowed max_memory
1138+
$js->eval(q{
1139+
var str = '';
1140+
while(1){ str += 'XXXX' }
1141+
});
1142+
1143+
=head2 C<set_timout(t)>
1144+
1145+
Enable/Disable timeout checking, to disable set the value to 0
1146+
this value is in seconds
1147+
1148+
my $js = JavaScript::Duktape->new();
1149+
1150+
# throw 'time out' Error if executed
1151+
# js code does not finish after 5 seconds
1152+
$js->set_timeout(5);
1153+
1154+
eval {
1155+
$js->eval(q{
1156+
while(1){}
1157+
});
1158+
};
1159+
1160+
print $@, "\n"; #RangeError: execution timeout
1161+
1162+
# disable timeout checking
1163+
$js->set_timeout(0);
1164+
1165+
# now will run infinitely
1166+
$js->eval(q{
1167+
while(1){}
1168+
});
1169+
1170+
This method can be used with duktape VM instance too
1171+
1172+
my $js = JavaScript::Duktape->new();
1173+
my $duk = $js->duk();
1174+
1175+
$duk->set_timeout(3);
1176+
$duk->peva_stringl(q{
1177+
while (1){}
1178+
});
1179+
1180+
print $duk->safe_to_string(-1); # Error: execution 'time out'
1181+
1182+
=head2 C<resize_memory(m)>
1183+
1184+
This method will have effect only if you intiated with max_memory option
1185+
1186+
my $js = JavaScript::Duktape->new( max_memory => 1024 * 256 );
1187+
1188+
1189+
eval {
1190+
$js->eval(q{
1191+
var buf = Buffer(( 1024 * 256 ) + 1000 );
1192+
print('does not reach');
1193+
});
1194+
};
1195+
1196+
print $@, "\n"; # Error: 'alloc failed'
1197+
1198+
$js->resize_memory( 1024 * 256 * 2 );
1199+
1200+
# now it will not throw
1201+
$js->eval(q{
1202+
var buf = Buffer(( 1024 * 256 ) + 1000 );
1203+
print('ok');
1204+
});
1205+
1206+
1207+
10821208
=head1 VM API
10831209
10841210
vm api corresponds to Duktape Engine API see L<http://duktape.org/api.html>
@@ -1309,16 +1435,25 @@ Mamod Mehyar C<< <[email protected]> >>
13091435
13101436
=head1 CONTRIBUTORS
13111437
1312-
Big thanks for the much appreciated contributors
1438+
Thanks for everyone who contributed to this module, either by code, bug reports, API design
1439+
or suggestions
13131440
13141441
=over 4
13151442
13161443
=item * Rodrigo de Oliveira L<@rodrigolive|https://github.com/rodrigolive>
13171444
13181445
=item * jomo666 L<@jomo666|https://github.com/jomo666>
13191446
1447+
=item * Viacheslav Tykhanovskyi L<@vti|https://github.com/vti>
1448+
1449+
=item * Slaven Rezić L<@eserte|https://github.com/eserte>
1450+
13201451
=back
13211452
1453+
=head1 APPRECIATION
1454+
1455+
Credits should go to L<< Duktape Javascript embeddable engine|http://duktape.org >> and it's creator L<< Sami Vaarala|https://github.com/svaarala >>
1456+
13221457
=head1 LICENSE
13231458
13241459
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

0 commit comments

Comments
 (0)