puma 6.4.3-java → 6.6.0-java

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/lib/puma/dsl.rb CHANGED
@@ -47,11 +47,13 @@ module Puma
47
47
  # | on_worker_boot | :before_worker_boot | inside, before |
48
48
  # | on_worker_shutdown | :before_worker_shutdown | inside, after |
49
49
  # | on_refork | :before_refork | inside |
50
+ # | after_refork | :after_refork | inside |
50
51
  #
51
52
  class DSL
52
53
  ON_WORKER_KEY = [String, Symbol].freeze
53
54
 
54
- # convenience method so logic can be used in CI
55
+ # Convenience method so logic can be used in CI.
56
+ #
55
57
  # @see ssl_bind
56
58
  #
57
59
  def self.ssl_bind_str(host, port, opts)
@@ -85,6 +87,7 @@ module Puma
85
87
  "&verify_mode=#{verify}#{tls_str}#{ca_additions}#{backlog_str}"
86
88
  else
87
89
  ssl_cipher_filter = opts[:ssl_cipher_filter] ? "&ssl_cipher_filter=#{opts[:ssl_cipher_filter]}" : nil
90
+ ssl_ciphersuites = opts[:ssl_ciphersuites] ? "&ssl_ciphersuites=#{opts[:ssl_ciphersuites]}" : nil
88
91
  v_flags = (ary = opts[:verification_flags]) ? "&verification_flags=#{Array(ary).join ','}" : nil
89
92
 
90
93
  cert_flags = (cert = opts[:cert]) ? "cert=#{Puma::Util.escape(cert)}" : nil
@@ -115,7 +118,7 @@ module Puma
115
118
  nil
116
119
  end
117
120
 
118
- "ssl://#{host}:#{port}?#{cert_flags}#{key_flags}#{password_flags}#{ssl_cipher_filter}" \
121
+ "ssl://#{host}:#{port}?#{cert_flags}#{key_flags}#{password_flags}#{ssl_cipher_filter}#{ssl_ciphersuites}" \
119
122
  "#{reuse_flag}&verify_mode=#{verify}#{tls_str}#{ca_additions}#{v_flags}#{backlog_str}#{low_latency_str}"
120
123
  end
121
124
  end
@@ -163,7 +166,10 @@ module Puma
163
166
  @options[key.to_sym] || default
164
167
  end
165
168
 
166
- # Load the named plugin for use by this configuration
169
+ # Load the named plugin for use by this configuration.
170
+ #
171
+ # @example
172
+ # plugin :tmp_restart
167
173
  #
168
174
  def plugin(name)
169
175
  @plugins << @config.load_plugin(name)
@@ -210,6 +216,7 @@ module Puma
210
216
  # activate_control_app 'unix:///var/run/pumactl.sock', { auth_token: '12345' }
211
217
  # @example
212
218
  # activate_control_app 'unix:///var/run/pumactl.sock', { no_token: true }
219
+ #
213
220
  def activate_control_app(url="auto", opts={})
214
221
  if url == "auto"
215
222
  path = Configuration.temp_path
@@ -235,8 +242,12 @@ module Puma
235
242
  @options[:control_url_umask] = opts[:umask] if opts[:umask]
236
243
  end
237
244
 
238
- # Load additional configuration from a file
239
- # Files get loaded later via Configuration#load
245
+ # Load additional configuration from a file.
246
+ # Files get loaded later via Configuration#load.
247
+ #
248
+ # @example
249
+ # load 'config/puma/production.rb'
250
+ #
240
251
  def load(file)
241
252
  @options[:config_files] ||= []
242
253
  @options[:config_files] << file
@@ -268,6 +279,7 @@ module Puma
268
279
  # bind 'tcp://0.0.0.0:9292?low_latency=false'
269
280
  # @example Socket permissions
270
281
  # bind 'unix:///var/run/puma.sock?umask=0111'
282
+ #
271
283
  # @see Puma::Runner#load_and_bind
272
284
  # @see Puma::Cluster#run
273
285
  #
@@ -302,39 +314,70 @@ module Puma
302
314
  #
303
315
  # @example Only bind to systemd activated sockets, ignoring other binds
304
316
  # bind_to_activated_sockets 'only'
317
+ #
305
318
  def bind_to_activated_sockets(bind=true)
306
319
  @options[:bind_to_activated_sockets] = bind
307
320
  end
308
321
 
309
- # Define the TCP port to bind to. Use +bind+ for more advanced options.
322
+ # Define the TCP port to bind to. Use `bind` for more advanced options.
323
+ #
324
+ # The default is +9292+.
310
325
  #
311
326
  # @example
312
- # port 9292
327
+ # port 3000
328
+ #
313
329
  def port(port, host=nil)
314
330
  host ||= default_host
315
331
  bind URI::Generic.build(scheme: 'tcp', host: host, port: Integer(port)).to_s
316
332
  end
317
333
 
318
334
  # Define how long the tcp socket stays open, if no data has been received.
335
+ #
336
+ # The default is 30 seconds.
337
+ #
338
+ # @example
339
+ # first_data_timeout 40
340
+ #
319
341
  # @see Puma::Server.new
342
+ #
320
343
  def first_data_timeout(seconds)
321
344
  @options[:first_data_timeout] = Integer(seconds)
322
345
  end
323
346
 
324
347
  # Define how long persistent connections can be idle before Puma closes them.
348
+ #
349
+ # The default is 20 seconds.
350
+ #
351
+ # @example
352
+ # persistent_timeout 30
353
+ #
325
354
  # @see Puma::Server.new
355
+ #
326
356
  def persistent_timeout(seconds)
327
357
  @options[:persistent_timeout] = Integer(seconds)
328
358
  end
329
359
 
330
360
  # If a new request is not received within this number of seconds, begin shutting down.
361
+ #
362
+ # The default is +nil+.
363
+ #
364
+ # @example
365
+ # idle_timeout 60
366
+ #
331
367
  # @see Puma::Server.new
368
+ #
332
369
  def idle_timeout(seconds)
333
370
  @options[:idle_timeout] = Integer(seconds)
334
371
  end
335
372
 
336
373
  # Work around leaky apps that leave garbage in Thread locals
337
374
  # across requests.
375
+ #
376
+ # The default is +false+.
377
+ #
378
+ # @example
379
+ # clean_thread_locals
380
+ #
338
381
  def clean_thread_locals(which=true)
339
382
  @options[:clean_thread_locals] = which
340
383
  end
@@ -342,6 +385,7 @@ module Puma
342
385
  # When shutting down, drain the accept socket of pending connections and
343
386
  # process them. This loops over the accept socket until there are no more
344
387
  # read events and then stops looking and waits for the requests to finish.
388
+ #
345
389
  # @see Puma::Server#graceful_shutdown
346
390
  #
347
391
  def drain_on_shutdown(which=true)
@@ -355,18 +399,22 @@ module Puma
355
399
  #
356
400
  # @example
357
401
  # environment 'production'
402
+ #
358
403
  def environment(environment)
359
404
  @options[:environment] = environment
360
405
  end
361
406
 
362
- # How long to wait for threads to stop when shutting them
363
- # down. Defaults to :forever. Specifying :immediately will cause
364
- # Puma to kill the threads immediately. Otherwise the value
365
- # is the number of seconds to wait.
407
+ # How long to wait for threads to stop when shutting them down.
408
+ # Specifying :immediately will cause Puma to kill the threads immediately.
409
+ # Otherwise the value is the number of seconds to wait.
366
410
  #
367
411
  # Puma always waits a few seconds after killing a thread for it to try
368
412
  # to finish up it's work, even in :immediately mode.
413
+ #
414
+ # The default is +:forever+.
415
+ #
369
416
  # @see Puma::Server#graceful_shutdown
417
+ #
370
418
  def force_shutdown_after(val=:forever)
371
419
  i = case val
372
420
  when :forever
@@ -389,9 +437,9 @@ module Puma
389
437
  # on_restart do
390
438
  # puts 'On restart...'
391
439
  # end
440
+ #
392
441
  def on_restart(&block)
393
- @options[:on_restart] ||= []
394
- @options[:on_restart] << block
442
+ process_hook :on_restart, nil, block, 'on_restart'
395
443
  end
396
444
 
397
445
  # Command to use to restart Puma. This should be just how to
@@ -400,6 +448,7 @@ module Puma
400
448
  #
401
449
  # @example
402
450
  # restart_command '/u/app/lolcat/bin/restart_puma'
451
+ #
403
452
  def restart_command(cmd)
404
453
  @options[:restart_cmd] = cmd.to_s
405
454
  end
@@ -408,31 +457,49 @@ module Puma
408
457
  #
409
458
  # @example
410
459
  # pidfile '/u/apps/lolcat/tmp/pids/puma.pid'
460
+ #
411
461
  def pidfile(path)
412
462
  @options[:pidfile] = path.to_s
413
463
  end
414
464
 
415
- # Disable request logging, if this isn't used it'll be enabled by default.
465
+ # Disable request logging, the inverse of `log_requests`.
466
+ #
467
+ # The default is +true+.
416
468
  #
417
469
  # @example
418
470
  # quiet
471
+ #
419
472
  def quiet(which=true)
420
473
  @options[:log_requests] = !which
421
474
  end
422
475
 
423
- # Enable request logging
476
+ # Enable request logging, the inverse of `quiet`.
477
+ #
478
+ # The default is +false+.
479
+ #
480
+ # @example
481
+ # log_requests
424
482
  #
425
483
  def log_requests(which=true)
426
484
  @options[:log_requests] = which
427
485
  end
428
486
 
429
487
  # Pass in a custom logging class instance
488
+ #
489
+ # @example
490
+ # custom_logger Logger.new('t.log')
491
+ #
430
492
  def custom_logger(custom_logger)
431
493
  @options[:custom_logger] = custom_logger
432
494
  end
433
495
 
434
496
  # Show debugging info
435
497
  #
498
+ # The default is +false+.
499
+ #
500
+ # @example
501
+ # debug
502
+ #
436
503
  def debug
437
504
  @options[:debug] = true
438
505
  end
@@ -443,6 +510,7 @@ module Puma
443
510
  #
444
511
  # @example
445
512
  # rackup '/u/apps/lolcat/config.ru'
513
+ #
446
514
  def rackup(path)
447
515
  @options[:rackup] ||= path.to_s
448
516
  end
@@ -450,21 +518,32 @@ module Puma
450
518
  # Allows setting `env['rack.url_scheme']`.
451
519
  # Only necessary if X-Forwarded-Proto is not being set by your proxy
452
520
  # Normal values are 'http' or 'https'.
521
+ #
453
522
  def rack_url_scheme(scheme=nil)
454
523
  @options[:rack_url_scheme] = scheme
455
524
  end
456
525
 
526
+ # Enable HTTP 103 Early Hints responses.
527
+ #
528
+ # The default is +nil+.
529
+ #
530
+ # @example
531
+ # early_hints
532
+ #
457
533
  def early_hints(answer=true)
458
534
  @options[:early_hints] = answer
459
535
  end
460
536
 
461
537
  # Redirect +STDOUT+ and +STDERR+ to files specified. The +append+ parameter
462
- # specifies whether the output is appended, the default is +false+.
538
+ # specifies whether the output is appended.
539
+ #
540
+ # The default is +false+.
463
541
  #
464
542
  # @example
465
543
  # stdout_redirect '/app/lolcat/log/stdout', '/app/lolcat/log/stderr'
466
544
  # @example
467
545
  # stdout_redirect '/app/lolcat/log/stdout', '/app/lolcat/log/stderr', true
546
+ #
468
547
  def stdout_redirect(stdout=nil, stderr=nil, append=false)
469
548
  @options[:redirect_stdout] = stdout
470
549
  @options[:redirect_stderr] = stderr
@@ -475,8 +554,9 @@ module Puma
475
554
  @options[:log_formatter] = block
476
555
  end
477
556
 
478
- # Configure +min+ to be the minimum number of threads to use to answer
479
- # requests and +max+ the maximum.
557
+ # Configure the number of threads to use to answer requests.
558
+ #
559
+ # It can be a single fixed number, or a +min+ and a +max+.
480
560
  #
481
561
  # The default is the environment variables +PUMA_MIN_THREADS+ / +PUMA_MAX_THREADS+
482
562
  # (or +MIN_THREADS+ / +MAX_THREADS+ if the +PUMA_+ variables aren't set).
@@ -484,10 +564,13 @@ module Puma
484
564
  # If these environment variables aren't set, the default is "0, 5" in MRI or "0, 16" for other interpreters.
485
565
  #
486
566
  # @example
567
+ # threads 5
568
+ # @example
487
569
  # threads 0, 16
488
570
  # @example
489
571
  # threads 5, 5
490
- def threads(min, max)
572
+ #
573
+ def threads(min, max = min)
491
574
  min = Integer(min)
492
575
  max = Integer(max)
493
576
  if min > max
@@ -527,6 +610,7 @@ module Puma
527
610
  # cert: path_to_cert,
528
611
  # key: path_to_key,
529
612
  # ssl_cipher_filter: cipher_filter, # optional
613
+ # ssl_ciphersuites: ciphersuites, # optional
530
614
  # verify_mode: verify_mode, # default 'none'
531
615
  # verification_flags: flags, # optional, not supported by JRuby
532
616
  # reuse: true # optional
@@ -549,6 +633,7 @@ module Puma
549
633
  # ssl_cipher_list: cipher_list, # optional
550
634
  # verify_mode: verify_mode # default 'none'
551
635
  # }
636
+ #
552
637
  def ssl_bind(host, port, opts = {})
553
638
  add_pem_values_to_options_store(opts)
554
639
  bind self.class.ssl_bind_str(host, port, opts)
@@ -559,6 +644,7 @@ module Puma
559
644
  #
560
645
  # @example
561
646
  # state_path '/u/apps/lolcat/tmp/pids/puma.state'
647
+ #
562
648
  def state_path(path)
563
649
  @options[:state] = path.to_s
564
650
  end
@@ -567,6 +653,7 @@ module Puma
567
653
  #
568
654
  # @example
569
655
  # state_permission 0600
656
+ #
570
657
  # @version 5.0.0
571
658
  #
572
659
  def state_permission(permission)
@@ -580,7 +667,12 @@ module Puma
580
667
  # set, otherwise 0.
581
668
  #
582
669
  # @note Cluster mode only.
670
+ #
671
+ # @example
672
+ # workers 2
673
+ #
583
674
  # @see Puma::Cluster
675
+ #
584
676
  def workers(count)
585
677
  @options[:workers] = count.to_i
586
678
  end
@@ -598,12 +690,24 @@ module Puma
598
690
  #
599
691
  # Moving from workers = 1 to workers = 0 will save 10-30% of memory use.
600
692
  #
693
+ # The default is +false+.
694
+ #
601
695
  # @note Cluster mode only.
696
+ #
697
+ # @example
698
+ # silence_single_worker_warning
699
+ #
602
700
  def silence_single_worker_warning
603
701
  @options[:silence_single_worker_warning] = true
604
702
  end
605
703
 
606
704
  # Disable warning message when running single mode with callback hook defined.
705
+ #
706
+ # The default is +false+.
707
+ #
708
+ # @example
709
+ # silence_fork_callback_warning
710
+ #
607
711
  def silence_fork_callback_warning
608
712
  @options[:silence_fork_callback_warning] = true
609
713
  end
@@ -618,15 +722,16 @@ module Puma
618
722
  # This can be called multiple times to add several hooks.
619
723
  #
620
724
  # @note Cluster mode only.
725
+ #
621
726
  # @example
622
727
  # before_fork do
623
728
  # puts "Starting workers..."
624
729
  # end
730
+ #
625
731
  def before_fork(&block)
626
732
  warn_if_in_single_mode('before_fork')
627
733
 
628
- @options[:before_fork] ||= []
629
- @options[:before_fork] << block
734
+ process_hook :before_fork, nil, block, 'before_fork'
630
735
  end
631
736
 
632
737
  # Code to run in a worker when it boots to setup
@@ -635,10 +740,12 @@ module Puma
635
740
  # This can be called multiple times to add several hooks.
636
741
  #
637
742
  # @note Cluster mode only.
743
+ #
638
744
  # @example
639
745
  # on_worker_boot do
640
746
  # puts 'Before worker boot...'
641
747
  # end
748
+ #
642
749
  def on_worker_boot(key = nil, &block)
643
750
  warn_if_in_single_mode('on_worker_boot')
644
751
 
@@ -646,17 +753,20 @@ module Puma
646
753
  end
647
754
 
648
755
  # Code to run immediately before a worker shuts
649
- # down (after it has finished processing HTTP requests). These hooks
756
+ # down (after it has finished processing HTTP requests). The worker's
757
+ # index is passed as an argument. These hooks
650
758
  # can block if necessary to wait for background operations unknown
651
759
  # to Puma to finish before the process terminates.
652
760
  #
653
761
  # This can be called multiple times to add several hooks.
654
762
  #
655
763
  # @note Cluster mode only.
764
+ #
656
765
  # @example
657
766
  # on_worker_shutdown do
658
767
  # puts 'On worker shutdown...'
659
768
  # end
769
+ #
660
770
  def on_worker_shutdown(key = nil, &block)
661
771
  warn_if_in_single_mode('on_worker_shutdown')
662
772
 
@@ -669,10 +779,12 @@ module Puma
669
779
  # This can be called multiple times to add several hooks.
670
780
  #
671
781
  # @note Cluster mode only.
782
+ #
672
783
  # @example
673
784
  # on_worker_fork do
674
785
  # puts 'Before worker fork...'
675
786
  # end
787
+ #
676
788
  def on_worker_fork(&block)
677
789
  warn_if_in_single_mode('on_worker_fork')
678
790
 
@@ -685,10 +797,12 @@ module Puma
685
797
  # This is called everytime a worker is to be started.
686
798
  #
687
799
  # @note Cluster mode only.
800
+ #
688
801
  # @example
689
802
  # after_worker_fork do
690
803
  # puts 'After worker fork...'
691
804
  # end
805
+ #
692
806
  def after_worker_fork(&block)
693
807
  warn_if_in_single_mode('after_worker_fork')
694
808
 
@@ -703,10 +817,22 @@ module Puma
703
817
  # on_booted do
704
818
  # puts 'After booting...'
705
819
  # end
820
+ #
706
821
  def on_booted(&block)
707
822
  @config.options[:events].on_booted(&block)
708
823
  end
709
824
 
825
+ # Code to run after puma is stopped (works for both: single and clustered)
826
+ #
827
+ # @example
828
+ # on_stopped do
829
+ # puts 'After stopping...'
830
+ # end
831
+ #
832
+ def on_stopped(&block)
833
+ @config.options[:events].on_stopped(&block)
834
+ end
835
+
710
836
  # When `fork_worker` is enabled, code to run in Worker 0
711
837
  # before all other workers are re-forked from this process,
712
838
  # after the server has temporarily stopped serving requests
@@ -719,16 +845,41 @@ module Puma
719
845
  # This can be called multiple times to add several hooks.
720
846
  #
721
847
  # @note Cluster mode with `fork_worker` enabled only.
848
+ #
722
849
  # @example
723
850
  # on_refork do
724
851
  # 3.times {GC.start}
725
852
  # end
853
+ #
726
854
  # @version 5.0.0
727
855
  #
728
856
  def on_refork(key = nil, &block)
857
+ warn_if_in_single_mode('on_refork')
858
+
729
859
  process_hook :before_refork, key, block, 'on_refork'
730
860
  end
731
861
 
862
+ # When `fork_worker` is enabled, code to run in Worker 0
863
+ # after all other workers are re-forked from this process,
864
+ # after the server has temporarily stopped serving requests
865
+ # (once per complete refork cycle).
866
+ #
867
+ # This can be used to re-open any connections to remote servers
868
+ # (database, Redis, ...) that were closed via on_refork.
869
+ #
870
+ # This can be called multiple times to add several hooks.
871
+ #
872
+ # @note Cluster mode with `fork_worker` enabled only.
873
+ #
874
+ # @example
875
+ # after_refork do
876
+ # puts 'After refork...'
877
+ # end
878
+ #
879
+ def after_refork(key = nil, &block)
880
+ process_hook :after_refork, key, block, 'after_refork'
881
+ end
882
+
732
883
  # Provide a block to be executed just before a thread is added to the thread
733
884
  # pool. Be careful: while the block executes, thread creation is delayed, and
734
885
  # probably a request will have to wait too! The new thread will not be added to
@@ -745,9 +896,9 @@ module Puma
745
896
  # on_thread_start do
746
897
  # puts 'On thread start...'
747
898
  # end
899
+ #
748
900
  def on_thread_start(&block)
749
- @options[:before_thread_start] ||= []
750
- @options[:before_thread_start] << block
901
+ process_hook :before_thread_start, nil, block, 'on_thread_start'
751
902
  end
752
903
 
753
904
  # Provide a block to be executed after a thread is trimmed from the thread
@@ -769,9 +920,9 @@ module Puma
769
920
  # on_thread_exit do
770
921
  # puts 'On thread exit...'
771
922
  # end
923
+ #
772
924
  def on_thread_exit(&block)
773
- @options[:before_thread_exit] ||= []
774
- @options[:before_thread_exit] << block
925
+ process_hook :before_thread_exit, nil, block, 'on_thread_exit'
775
926
  end
776
927
 
777
928
  # Code to run out-of-band when the worker is idle.
@@ -783,6 +934,7 @@ module Puma
783
934
  # or scheduling asynchronous tasks to execute after a response.
784
935
  #
785
936
  # This can be called multiple times to add several hooks.
937
+ #
786
938
  def out_of_band(&block)
787
939
  process_hook :out_of_band, nil, block, 'out_of_band'
788
940
  end
@@ -793,16 +945,21 @@ module Puma
793
945
  #
794
946
  # @example
795
947
  # directory '/u/apps/lolcat'
948
+ #
796
949
  def directory(dir)
797
950
  @options[:directory] = dir.to_s
798
951
  end
799
952
 
800
953
  # Preload the application before starting the workers; this conflicts with
801
- # phased restart feature. On by default if your app uses more than 1 worker.
954
+ # phased restart feature.
955
+ #
956
+ # The default is +true+ if your app uses more than 1 worker.
802
957
  #
803
958
  # @note Cluster mode only.
959
+ #
804
960
  # @example
805
961
  # preload_app!
962
+ #
806
963
  def preload_app!(answer=true)
807
964
  @options[:preload_app] = answer
808
965
  end
@@ -814,6 +971,7 @@ module Puma
814
971
  # lowlevel_error_handler do |err|
815
972
  # [200, {}, ["error page"]]
816
973
  # end
974
+ #
817
975
  def lowlevel_error_handler(obj=nil, &block)
818
976
  obj ||= block
819
977
  raise "Provide either a #call'able or a block" unless obj
@@ -833,23 +991,26 @@ module Puma
833
991
  # new Bundler context and thus can float around as the release
834
992
  # dictates.
835
993
  #
836
- # @see extra_runtime_dependencies
837
- #
838
994
  # @note This is incompatible with +preload_app!+.
839
995
  # @note This is only supported for RubyGems 2.2+
996
+ #
997
+ # @see extra_runtime_dependencies
998
+ #
840
999
  def prune_bundler(answer=true)
841
1000
  @options[:prune_bundler] = answer
842
1001
  end
843
1002
 
844
- # By default, Puma will raise SignalException when SIGTERM is received. In
845
- # environments where SIGTERM is something expected, you can suppress these
846
- # with this option.
1003
+ # Raises a SignalException when SIGTERM is received. In environments where
1004
+ # SIGTERM is something expected, you can suppress these with this option.
847
1005
  #
848
1006
  # This can be useful for example in Kubernetes, where rolling restart is
849
- # guaranteed usually on infrastructure level.
1007
+ # guaranteed usually on the infrastructure level.
1008
+ #
1009
+ # The default is +true+.
850
1010
  #
851
1011
  # @example
852
1012
  # raise_exception_on_sigterm false
1013
+ #
853
1014
  # @see Puma::Launcher#setup_signals
854
1015
  # @see Puma::Cluster#setup_signals
855
1016
  #
@@ -868,6 +1029,7 @@ module Puma
868
1029
  # extra_runtime_dependencies ['gem_name_1', 'gem_name_2']
869
1030
  # @example
870
1031
  # extra_runtime_dependencies ['puma_worker_killer', 'puma-heroku']
1032
+ #
871
1033
  # @see Puma::Launcher#extra_runtime_deps_directories
872
1034
  #
873
1035
  def extra_runtime_dependencies(answer = [])
@@ -879,21 +1041,26 @@ module Puma
879
1041
  # If you do not specify a tag, Puma will infer it. If you do not want Puma
880
1042
  # to add a tag, use an empty string.
881
1043
  #
1044
+ # The default is the current file or directory base name.
1045
+ #
882
1046
  # @example
883
1047
  # tag 'app name'
884
1048
  # @example
885
1049
  # tag ''
1050
+ #
886
1051
  def tag(string)
887
1052
  @options[:tag] = string.to_s
888
1053
  end
889
1054
 
890
1055
  # Change the default interval for checking workers.
891
1056
  #
892
- # The default value is 5 seconds.
1057
+ # The default is 5 seconds.
893
1058
  #
894
1059
  # @note Cluster mode only.
1060
+ #
895
1061
  # @example
896
- # worker_check_interval 5
1062
+ # worker_check_interval 10
1063
+ #
897
1064
  # @see Puma::Cluster#check_workers
898
1065
  #
899
1066
  def worker_check_interval(interval)
@@ -906,11 +1073,14 @@ module Puma
906
1073
  # Setting this value will not protect against slow requests.
907
1074
  #
908
1075
  # This value must be greater than worker_check_interval.
909
- # The default value is 60 seconds.
1076
+ #
1077
+ # The default is 60 seconds.
910
1078
  #
911
1079
  # @note Cluster mode only.
1080
+ #
912
1081
  # @example
913
1082
  # worker_timeout 60
1083
+ #
914
1084
  # @see Puma::Cluster::Worker#ping_timeout
915
1085
  #
916
1086
  def worker_timeout(timeout)
@@ -926,12 +1096,13 @@ module Puma
926
1096
 
927
1097
  # Change the default worker timeout for booting.
928
1098
  #
929
- # If unspecified, this defaults to the value of worker_timeout.
1099
+ # The default is the value of `worker_timeout`.
930
1100
  #
931
1101
  # @note Cluster mode only.
932
1102
  #
933
1103
  # @example
934
1104
  # worker_boot_timeout 60
1105
+ #
935
1106
  # @see Puma::Cluster::Worker#ping_timeout
936
1107
  #
937
1108
  def worker_boot_timeout(timeout)
@@ -940,7 +1111,13 @@ module Puma
940
1111
 
941
1112
  # Set the timeout for worker shutdown.
942
1113
  #
1114
+ # The default is 60 seconds.
1115
+ #
943
1116
  # @note Cluster mode only.
1117
+ #
1118
+ # @example
1119
+ # worker_shutdown_timeout 90
1120
+ #
944
1121
  # @see Puma::Cluster::Worker#term
945
1122
  #
946
1123
  def worker_shutdown_timeout(timeout)
@@ -956,9 +1133,13 @@ module Puma
956
1133
  # 2. **:oldest** - the oldest workers (i.e. the workers that were started
957
1134
  # the longest time ago) will be culled.
958
1135
  #
1136
+ # The default is +:youngest+.
1137
+ #
959
1138
  # @note Cluster mode only.
1139
+ #
960
1140
  # @example
961
1141
  # worker_culling_strategy :oldest
1142
+ #
962
1143
  # @see Puma::Cluster#cull_workers
963
1144
  #
964
1145
  def worker_culling_strategy(strategy)
@@ -971,7 +1152,7 @@ module Puma
971
1152
  @options[:worker_culling_strategy] = strategy
972
1153
  end
973
1154
 
974
- # When set to true (the default), workers accept all requests
1155
+ # When set to true, workers accept all requests
975
1156
  # and queue them before passing them to the handlers.
976
1157
  # When set to false, each worker process accepts exactly as
977
1158
  # many requests as it is configured to simultaneously handle.
@@ -984,7 +1165,11 @@ module Puma
984
1165
  # slow clients will occupy a handler thread while the request
985
1166
  # is being sent. A reverse proxy, such as nginx, can handle
986
1167
  # slow clients and queue requests before they reach Puma.
1168
+ #
1169
+ # The default is +true+.
1170
+ #
987
1171
  # @see Puma::Server
1172
+ #
988
1173
  def queue_requests(answer=true)
989
1174
  @options[:queue_requests] = answer
990
1175
  end
@@ -1002,9 +1187,13 @@ module Puma
1002
1187
  # listening on the socket, allowing workers which are not processing any
1003
1188
  # requests to pick up new requests first.
1004
1189
  #
1190
+ # The default is 0.005 seconds.
1191
+ #
1005
1192
  # Only works on MRI. For all other interpreters, this setting does nothing.
1193
+ #
1006
1194
  # @see Puma::Server#handle_servers
1007
1195
  # @see Puma::ThreadPool#wait_for_less_busy_worker
1196
+ #
1008
1197
  # @version 5.0.0
1009
1198
  #
1010
1199
  def wait_for_less_busy_worker(val=0.005)
@@ -1018,7 +1207,7 @@ module Puma
1018
1207
  #
1019
1208
  # There are 5 possible values:
1020
1209
  #
1021
- # 1. **:socket** (the default) - read the peername from the socket using the
1210
+ # 1. **:socket** - read the peername from the socket using the
1022
1211
  # syscall. This is the normal behavior. If this fails for any reason (e.g.,
1023
1212
  # if the peer disconnects between the connection being accepted and the getpeername
1024
1213
  # system call), Puma will return "0.0.0.0"
@@ -1036,6 +1225,11 @@ module Puma
1036
1225
  # you wish. Because Puma never uses this field anyway, it's format is
1037
1226
  # entirely in your hands.
1038
1227
  #
1228
+ # The default is +:socket+.
1229
+ #
1230
+ # @example
1231
+ # set_remote_address :localhost
1232
+ #
1039
1233
  def set_remote_address(val=:socket)
1040
1234
  case val
1041
1235
  when :socket
@@ -1076,6 +1270,7 @@ module Puma
1076
1270
  # (default 1000), or pass 0 to disable auto refork.
1077
1271
  #
1078
1272
  # @note Cluster mode only.
1273
+ #
1079
1274
  # @version 5.0.0
1080
1275
  #
1081
1276
  def fork_worker(after_requests=1000)
@@ -1085,10 +1280,41 @@ module Puma
1085
1280
  # The number of requests to attempt inline before sending a client back to
1086
1281
  # the reactor to be subject to normal ordering.
1087
1282
  #
1283
+ # The default is 10.
1284
+ #
1285
+ # @example
1286
+ # max_fast_inline 20
1287
+ #
1088
1288
  def max_fast_inline(num_of_requests)
1089
1289
  @options[:max_fast_inline] = Float(num_of_requests)
1090
1290
  end
1091
1291
 
1292
+ # When `true`, keep-alive connections are maintained on inbound requests.
1293
+ # Enabling this setting reduces the number of TCP operations, reducing response
1294
+ # times for connections that can send multiple requests in a single connection.
1295
+ #
1296
+ # When Puma receives more incoming connections than available Puma threads,
1297
+ # enabling the keep-alive behavior may result in processing requests out-of-order,
1298
+ # increasing overall response time variance. Increased response time variance
1299
+ # means that the overall average of response times might not change, but more
1300
+ # outliers will exist. Those long-tail outliers may significantly affect response
1301
+ # times for some processed requests.
1302
+ #
1303
+ # When `false`, Puma closes the connection after each request, requiring the
1304
+ # client to open a new request. Disabling this setting guarantees that requests
1305
+ # will be processed in the order they are fully received, decreasing response
1306
+ # variance and eliminating long-tail outliers caused by keep-alive behavior.
1307
+ # The trade-off is that the number of TCP operations required will increase.
1308
+ #
1309
+ # The default is +true+.
1310
+ #
1311
+ # @example
1312
+ # enable_keep_alives false
1313
+ #
1314
+ def enable_keep_alives(enabled=true)
1315
+ @options[:enable_keep_alives] = enabled
1316
+ end
1317
+
1092
1318
  # Specify the backend for the IO selector.
1093
1319
  #
1094
1320
  # Provided values will be passed directly to +NIO::Selector.new+, with the
@@ -1108,6 +1334,14 @@ module Puma
1108
1334
  @options[:io_selector_backend] = backend.to_sym
1109
1335
  end
1110
1336
 
1337
+ # Ensures +STDOUT+ and +STDERR+ is immediately flushed to the underlying
1338
+ # operating system and is not buffered internally
1339
+ #
1340
+ # The default is +true+.
1341
+ #
1342
+ # @example
1343
+ # mutate_stdout_and_stderr_to_sync_on_write false
1344
+ #
1111
1345
  def mutate_stdout_and_stderr_to_sync_on_write(enabled=true)
1112
1346
  @options[:mutate_stdout_and_stderr_to_sync_on_write] = enabled
1113
1347
  end
@@ -1119,8 +1353,12 @@ module Puma
1119
1353
  #
1120
1354
  # When no Content-Length http header is present, it is compared against the
1121
1355
  # size of the body of the request.
1122
- #
1123
- # The default value for http_content_length_limit is nil.
1356
+ #
1357
+ # The default is +nil+.
1358
+ #
1359
+ # @example
1360
+ # http_content_length_limit 2_000_000_000
1361
+ #
1124
1362
  def http_content_length_limit(limit)
1125
1363
  @options[:http_content_length_limit] = limit
1126
1364
  end
@@ -1161,6 +1399,7 @@ module Puma
1161
1399
 
1162
1400
  # To avoid adding cert_pem and key_pem as URI params, we store them on the
1163
1401
  # options[:store] from where Puma binder knows how to find and extract them.
1402
+ #
1164
1403
  def add_pem_values_to_options_store(opts)
1165
1404
  return if defined?(JRUBY_VERSION)
1166
1405
 
@@ -1196,8 +1435,8 @@ module Puma
1196
1435
  if workers_val == 0
1197
1436
  log_string =
1198
1437
  "Warning: You specified code to run in a `#{hook_name}` block, " \
1199
- "but Puma is not configured to run in cluster mode (worker count > 0 ), " \
1200
- "so your `#{hook_name}` block did not run"
1438
+ "but Puma is not configured to run in cluster mode (worker count > 0), " \
1439
+ "so your `#{hook_name}` block will not run."
1201
1440
 
1202
1441
  LogWriter.stdio.log(log_string)
1203
1442
  end