File size: 117,513 Bytes
d1ceb73
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
2868
2869
2870
2871
2872
2873
2874
2875
2876
2877
2878
2879
2880
2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
2910
2911
2912
2913
2914
2915
2916
2917
2918
2919
2920
2921
2922
2923
2924
2925
2926
2927
2928
2929
2930
2931
2932
2933
2934
2935
2936
2937
2938
2939
2940
2941
2942
2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
2953
2954
2955
2956
2957
2958
2959
2960
2961
2962
2963
2964
2965
2966
2967
2968
2969
2970
2971
2972
2973
2974
2975
2976
2977
2978
2979
2980
2981
2982
2983
2984
2985
2986
2987
2988
2989
2990
2991
2992
2993
2994
2995
2996
2997
2998
2999
3000
3001
3002
3003
3004
3005
3006
3007
3008
3009
3010
3011
3012
3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
3023
3024
3025
3026
3027
3028
3029
3030
3031
3032
3033
3034
3035
3036
3037
3038
3039
3040
3041
3042
3043
3044
3045
3046
3047
3048
3049
3050
3051
3052
3053
3054
3055
3056
3057
3058
3059
3060
3061
3062
3063
3064
3065
3066
3067
3068
3069
3070
3071
3072
3073
3074
3075
3076
3077
3078
3079
3080
3081
3082
3083
3084
3085
3086
3087
3088
3089
3090
3091
3092
3093
3094
3095
3096
3097
3098
3099
3100
3101
3102
3103
3104
3105
3106
3107
3108
3109
3110
3111
3112
3113
3114
3115
3116
3117
3118
3119
3120
3121
3122
3123
3124
3125
3126
3127
3128
3129
3130
3131
3132
3133
3134
3135
3136
3137
3138
3139
3140
3141
3142
3143
3144
3145
3146
3147
3148
3149
3150
3151
3152
3153
3154
3155
3156
3157
3158
3159
3160
3161
3162
3163
3164
3165
3166
3167
3168
3169
3170
3171
3172
3173
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
"""A tornado based Jupyter server."""

# Copyright (c) Jupyter Development Team.
# Distributed under the terms of the Modified BSD License.
from __future__ import annotations

import datetime
import errno
import gettext
import hashlib
import hmac
import ipaddress
import json
import logging
import mimetypes
import os
import pathlib
import random
import re
import select
import signal
import socket
import stat
import sys
import threading
import time
import typing as t
import urllib
import warnings
from base64 import encodebytes
from pathlib import Path

import jupyter_client
from jupyter_client.kernelspec import KernelSpecManager
from jupyter_client.manager import KernelManager
from jupyter_client.session import Session
from jupyter_core.application import JupyterApp, base_aliases, base_flags
from jupyter_core.paths import jupyter_runtime_dir
from jupyter_events.logger import EventLogger
from nbformat.sign import NotebookNotary
from tornado import httpserver, ioloop, web
from tornado.httputil import url_concat
from tornado.log import LogFormatter, access_log, app_log, gen_log
from tornado.netutil import bind_sockets
from tornado.routing import Matcher, Rule

if not sys.platform.startswith("win"):
    from tornado.netutil import bind_unix_socket

if sys.platform.startswith("win"):
    try:
        import colorama

        colorama.init()
    except ImportError:
        pass

from traitlets import (
    Any,
    Bool,
    Bytes,
    Dict,
    Float,
    Instance,
    Integer,
    List,
    TraitError,
    Type,
    Unicode,
    Union,
    default,
    observe,
    validate,
)
from traitlets.config import Config
from traitlets.config.application import boolean_flag, catch_config_error

from jupyter_server import (
    DEFAULT_EVENTS_SCHEMA_PATH,
    DEFAULT_JUPYTER_SERVER_PORT,
    DEFAULT_STATIC_FILES_PATH,
    DEFAULT_TEMPLATE_PATH_LIST,
    JUPYTER_SERVER_EVENTS_URI,
    __version__,
)
from jupyter_server._sysinfo import get_sys_info
from jupyter_server._tz import utcnow
from jupyter_server.auth.authorizer import AllowAllAuthorizer, Authorizer
from jupyter_server.auth.identity import (
    IdentityProvider,
    LegacyIdentityProvider,
    PasswordIdentityProvider,
)
from jupyter_server.auth.login import LoginHandler
from jupyter_server.auth.logout import LogoutHandler
from jupyter_server.base.handlers import (
    FileFindHandler,
    MainHandler,
    RedirectWithParams,
    Template404,
)
from jupyter_server.extension.config import ExtensionConfigManager
from jupyter_server.extension.manager import ExtensionManager
from jupyter_server.extension.serverextension import ServerExtensionApp
from jupyter_server.gateway.connections import GatewayWebSocketConnection
from jupyter_server.gateway.gateway_client import GatewayClient
from jupyter_server.gateway.managers import (
    GatewayKernelSpecManager,
    GatewayMappingKernelManager,
    GatewaySessionManager,
)
from jupyter_server.log import log_request
from jupyter_server.services.config import ConfigManager
from jupyter_server.services.contents.filemanager import (
    AsyncFileContentsManager,
    FileContentsManager,
)
from jupyter_server.services.contents.largefilemanager import AsyncLargeFileManager
from jupyter_server.services.contents.manager import AsyncContentsManager, ContentsManager
from jupyter_server.services.kernels.connection.base import BaseKernelWebsocketConnection
from jupyter_server.services.kernels.connection.channels import ZMQChannelsWebsocketConnection
from jupyter_server.services.kernels.kernelmanager import (
    AsyncMappingKernelManager,
    MappingKernelManager,
)
from jupyter_server.services.sessions.sessionmanager import SessionManager
from jupyter_server.utils import (
    JupyterServerAuthWarning,
    check_pid,
    fetch,
    unix_socket_in_use,
    url_escape,
    url_path_join,
    urlencode_unix_socket_path,
)

try:
    import resource
except ImportError:
    # Windows
    resource = None  # type:ignore[assignment]

from jinja2 import Environment, FileSystemLoader
from jupyter_core.paths import secure_write
from jupyter_core.utils import ensure_async

from jupyter_server.transutils import _i18n, trans
from jupyter_server.utils import pathname2url, urljoin

# the minimum viable tornado version: needs to be kept in sync with setup.py
MIN_TORNADO = (6, 1, 0)

try:
    import tornado

    assert tornado.version_info >= MIN_TORNADO
except (ImportError, AttributeError, AssertionError) as e:  # pragma: no cover
    raise ImportError(_i18n("The Jupyter Server requires tornado >=%s.%s.%s") % MIN_TORNADO) from e

try:
    import resource
except ImportError:
    # Windows
    resource = None  # type:ignore[assignment]

# -----------------------------------------------------------------------------
# Module globals
# -----------------------------------------------------------------------------

_examples = """
jupyter server                       # start the server
jupyter server  --certfile=mycert.pem # use SSL/TLS certificate
jupyter server password              # enter a password to protect the server
"""

JUPYTER_SERVICE_HANDLERS = {
    "auth": None,
    "api": ["jupyter_server.services.api.handlers"],
    "config": ["jupyter_server.services.config.handlers"],
    "contents": ["jupyter_server.services.contents.handlers"],
    "files": ["jupyter_server.files.handlers"],
    "kernels": [
        "jupyter_server.services.kernels.handlers",
    ],
    "kernelspecs": [
        "jupyter_server.kernelspecs.handlers",
        "jupyter_server.services.kernelspecs.handlers",
    ],
    "nbconvert": [
        "jupyter_server.nbconvert.handlers",
        "jupyter_server.services.nbconvert.handlers",
    ],
    "security": ["jupyter_server.services.security.handlers"],
    "sessions": ["jupyter_server.services.sessions.handlers"],
    "shutdown": ["jupyter_server.services.shutdown"],
    "view": ["jupyter_server.view.handlers"],
    "events": ["jupyter_server.services.events.handlers"],
}

# Added for backwards compatibility from classic notebook server.
DEFAULT_SERVER_PORT = DEFAULT_JUPYTER_SERVER_PORT

# -----------------------------------------------------------------------------
# Helper functions
# -----------------------------------------------------------------------------


def random_ports(port: int, n: int) -> t.Generator[int, None, None]:
    """Generate a list of n random ports near the given port.

    The first 5 ports will be sequential, and the remaining n-5 will be
    randomly selected in the range [port-2*n, port+2*n].
    """
    for i in range(min(5, n)):
        yield port + i
    for _ in range(n - 5):
        yield max(1, port + random.randint(-2 * n, 2 * n))  # noqa: S311


def load_handlers(name: str) -> t.Any:
    """Load the (URL pattern, handler) tuples for each component."""
    mod = __import__(name, fromlist=["default_handlers"])
    return mod.default_handlers


# -----------------------------------------------------------------------------
# The Tornado web application
# -----------------------------------------------------------------------------


class ServerWebApplication(web.Application):
    """A server web application."""

    def __init__(
        self,
        jupyter_app,
        default_services,
        kernel_manager,
        contents_manager,
        session_manager,
        kernel_spec_manager,
        config_manager,
        event_logger,
        extra_services,
        log,
        base_url,
        default_url,
        settings_overrides,
        jinja_env_options,
        *,
        authorizer=None,
        identity_provider=None,
        kernel_websocket_connection_class=None,
        websocket_ping_interval=None,
        websocket_ping_timeout=None,
    ):
        """Initialize a server web application."""
        if identity_provider is None:
            warnings.warn(
                "identity_provider unspecified. Using default IdentityProvider."
                " Specify an identity_provider to avoid this message.",
                RuntimeWarning,
                stacklevel=2,
            )
            identity_provider = IdentityProvider(parent=jupyter_app)

        if authorizer is None:
            warnings.warn(
                "authorizer unspecified. Using permissive AllowAllAuthorizer."
                " Specify an authorizer to avoid this message.",
                JupyterServerAuthWarning,
                stacklevel=2,
            )
            authorizer = AllowAllAuthorizer(parent=jupyter_app, identity_provider=identity_provider)

        settings = self.init_settings(
            jupyter_app,
            kernel_manager,
            contents_manager,
            session_manager,
            kernel_spec_manager,
            config_manager,
            event_logger,
            extra_services,
            log,
            base_url,
            default_url,
            settings_overrides,
            jinja_env_options,
            authorizer=authorizer,
            identity_provider=identity_provider,
            kernel_websocket_connection_class=kernel_websocket_connection_class,
            websocket_ping_interval=websocket_ping_interval,
            websocket_ping_timeout=websocket_ping_timeout,
        )
        handlers = self.init_handlers(default_services, settings)

        undecorated_methods = []
        for matcher, handler, *_ in handlers:
            undecorated_methods.extend(self._check_handler_auth(matcher, handler))

        if undecorated_methods:
            message = (
                "Core endpoints without @allow_unauthenticated, @ws_authenticated, nor @web.authenticated:\n"
                + "\n".join(undecorated_methods)
            )
            if jupyter_app.allow_unauthenticated_access:
                warnings.warn(
                    message,
                    JupyterServerAuthWarning,
                    stacklevel=2,
                )
            else:
                raise Exception(message)

        super().__init__(handlers, **settings)

    def add_handlers(self, host_pattern, host_handlers):
        undecorated_methods = []
        for rule in host_handlers:
            if isinstance(rule, Rule):
                matcher = rule.matcher
                handler = rule.target
            else:
                matcher, handler, *_ = rule
            undecorated_methods.extend(self._check_handler_auth(matcher, handler))

        if undecorated_methods and not self.settings["allow_unauthenticated_access"]:
            message = (
                "Extension endpoints without @allow_unauthenticated, @ws_authenticated, nor @web.authenticated:\n"
                + "\n".join(undecorated_methods)
            )
            warnings.warn(
                message,
                JupyterServerAuthWarning,
                stacklevel=2,
            )

        return super().add_handlers(host_pattern, host_handlers)

    def init_settings(
        self,
        jupyter_app,
        kernel_manager,
        contents_manager,
        session_manager,
        kernel_spec_manager,
        config_manager,
        event_logger,
        extra_services,
        log,
        base_url,
        default_url,
        settings_overrides,
        jinja_env_options=None,
        *,
        authorizer=None,
        identity_provider=None,
        kernel_websocket_connection_class=None,
        websocket_ping_interval=None,
        websocket_ping_timeout=None,
    ):
        """Initialize settings for the web application."""
        _template_path = settings_overrides.get(
            "template_path",
            jupyter_app.template_file_path,
        )
        if isinstance(_template_path, str):
            _template_path = (_template_path,)
        template_path = [os.path.expanduser(path) for path in _template_path]

        jenv_opt: dict[str, t.Any] = {"autoescape": True}
        jenv_opt.update(jinja_env_options if jinja_env_options else {})

        env = Environment(  # noqa: S701
            loader=FileSystemLoader(template_path), extensions=["jinja2.ext.i18n"], **jenv_opt
        )
        sys_info = get_sys_info()

        base_dir = os.path.realpath(os.path.join(__file__, "..", ".."))
        nbui = gettext.translation(
            "nbui",
            localedir=os.path.join(base_dir, "jupyter_server/i18n"),
            fallback=True,
        )
        env.install_gettext_translations(nbui, newstyle=False)

        if sys_info["commit_source"] == "repository":
            # don't cache (rely on 304) when working from master
            version_hash = ""
        else:
            # reset the cache on server restart
            utc = datetime.timezone.utc
            version_hash = datetime.datetime.now(tz=utc).strftime("%Y%m%d%H%M%S")

        now = utcnow()

        root_dir = contents_manager.root_dir
        home = os.path.expanduser("~")
        if root_dir.startswith(home + os.path.sep):
            # collapse $HOME to ~
            root_dir = "~" + root_dir[len(home) :]

        settings = {
            # basics
            "log_function": log_request,
            "base_url": base_url,
            "default_url": default_url,
            "template_path": template_path,
            "static_path": jupyter_app.static_file_path,
            "static_custom_path": jupyter_app.static_custom_path,
            "static_handler_class": FileFindHandler,
            "static_url_prefix": url_path_join(base_url, "/static/"),
            "static_handler_args": {
                # don't cache custom.js
                "no_cache_paths": [url_path_join(base_url, "static", "custom")],
            },
            "version_hash": version_hash,
            # kernel message protocol over websocket
            "kernel_ws_protocol": jupyter_app.kernel_ws_protocol,
            # rate limits
            "limit_rate": jupyter_app.limit_rate,
            "iopub_msg_rate_limit": jupyter_app.iopub_msg_rate_limit,
            "iopub_data_rate_limit": jupyter_app.iopub_data_rate_limit,
            "rate_limit_window": jupyter_app.rate_limit_window,
            # authentication
            "cookie_secret": jupyter_app.cookie_secret,
            "login_url": url_path_join(base_url, "/login"),
            "xsrf_cookies": True,
            "disable_check_xsrf": jupyter_app.disable_check_xsrf,
            "allow_unauthenticated_access": jupyter_app.allow_unauthenticated_access,
            "allow_remote_access": jupyter_app.allow_remote_access,
            "local_hostnames": jupyter_app.local_hostnames,
            "authenticate_prometheus": jupyter_app.authenticate_prometheus,
            # managers
            "kernel_manager": kernel_manager,
            "contents_manager": contents_manager,
            "session_manager": session_manager,
            "kernel_spec_manager": kernel_spec_manager,
            "config_manager": config_manager,
            "authorizer": authorizer,
            "identity_provider": identity_provider,
            "event_logger": event_logger,
            "kernel_websocket_connection_class": kernel_websocket_connection_class,
            "websocket_ping_interval": websocket_ping_interval,
            "websocket_ping_timeout": websocket_ping_timeout,
            # handlers
            "extra_services": extra_services,
            # Jupyter stuff
            "started": now,
            # place for extensions to register activity
            # so that they can prevent idle-shutdown
            "last_activity_times": {},
            "jinja_template_vars": jupyter_app.jinja_template_vars,
            "websocket_url": jupyter_app.websocket_url,
            "shutdown_button": jupyter_app.quit_button,
            "config": jupyter_app.config,
            "config_dir": jupyter_app.config_dir,
            "allow_password_change": jupyter_app.allow_password_change,
            "server_root_dir": root_dir,
            "jinja2_env": env,
            "serverapp": jupyter_app,
        }

        # allow custom overrides for the tornado web app.
        settings.update(settings_overrides)

        if base_url and "xsrf_cookie_kwargs" not in settings:
            # default: set xsrf cookie on base_url
            settings["xsrf_cookie_kwargs"] = {"path": base_url}
        return settings

    def init_handlers(self, default_services, settings):
        """Load the (URL pattern, handler) tuples for each component."""
        # Order matters. The first handler to match the URL will handle the request.
        handlers = []
        # load extra services specified by users before default handlers
        for service in settings["extra_services"]:
            handlers.extend(load_handlers(service))

        # Load default services. Raise exception if service not
        # found in JUPYTER_SERVICE_HANLDERS.
        for service in default_services:
            if service in JUPYTER_SERVICE_HANDLERS:
                locations = JUPYTER_SERVICE_HANDLERS[service]
                if locations is not None:
                    for loc in locations:
                        handlers.extend(load_handlers(loc))
            else:
                msg = (
                    f"{service} is not recognized as a jupyter_server "
                    "service. If this is a custom service, "
                    "try adding it to the "
                    "`extra_services` list."
                )
                raise Exception(msg)

        # Add extra handlers from contents manager.
        handlers.extend(settings["contents_manager"].get_extra_handlers())
        # And from identity provider
        handlers.extend(settings["identity_provider"].get_handlers())

        # register base handlers last
        handlers.extend(load_handlers("jupyter_server.base.handlers"))

        if settings["default_url"] != settings["base_url"]:
            # set the URL that will be redirected from `/`
            handlers.append(
                (
                    r"/?",
                    RedirectWithParams,
                    {
                        "url": settings["default_url"],
                        "permanent": False,  # want 302, not 301
                    },
                )
            )
        else:
            handlers.append((r"/", MainHandler))

        # prepend base_url onto the patterns that we match
        new_handlers = []
        for handler in handlers:
            pattern = url_path_join(settings["base_url"], handler[0])
            new_handler = (pattern, *list(handler[1:]))
            new_handlers.append(new_handler)
        # add 404 on the end, which will catch everything that falls through
        new_handlers.append((r"(.*)", Template404))
        return new_handlers

    def last_activity(self):
        """Get a UTC timestamp for when the server last did something.

        Includes: API activity, kernel activity, kernel shutdown, and terminal
        activity.
        """
        sources = [
            self.settings["started"],
            self.settings["kernel_manager"].last_kernel_activity,
        ]
        # Any setting that ends with a key that ends with `_last_activity` is
        # counted here. This provides a hook for extensions to add a last activity
        # setting to the server.
        sources.extend(
            [val for key, val in self.settings.items() if key.endswith("_last_activity")]
        )
        sources.extend(self.settings["last_activity_times"].values())
        return max(sources)

    def _check_handler_auth(
        self, matcher: t.Union[str, Matcher], handler: type[web.RequestHandler]
    ):
        missing_authentication = []
        for method_name in handler.SUPPORTED_METHODS:
            method = getattr(handler, method_name.lower())
            is_unimplemented = method == web.RequestHandler._unimplemented_method
            is_allowlisted = hasattr(method, "__allow_unauthenticated")
            is_blocklisted = _has_tornado_web_authenticated(method)
            if not is_unimplemented and not is_allowlisted and not is_blocklisted:
                missing_authentication.append(
                    f"- {method_name} of {handler.__name__} registered for {matcher}"
                )
        return missing_authentication


def _has_tornado_web_authenticated(method: t.Callable[..., t.Any]) -> bool:
    """Check if given method was decorated with @web.authenticated.

    Note: it is ok if we reject on @authorized @web.authenticated
    because the correct order is @web.authenticated @authorized.
    """
    if not hasattr(method, "__wrapped__"):
        return False
    if not hasattr(method, "__code__"):
        return False
    code = method.__code__
    if hasattr(code, "co_qualname"):
        # new in 3.11
        return code.co_qualname.startswith("authenticated")  # type:ignore[no-any-return]
    elif hasattr(code, "co_filename"):
        return code.co_filename.replace("\\", "/").endswith("tornado/web.py")
    return False


class JupyterPasswordApp(JupyterApp):
    """Set a password for the Jupyter server.

    Setting a password secures the Jupyter server
    and removes the need for token-based authentication.
    """

    description: str = __doc__

    def _config_file_default(self):
        """the default config file."""
        return os.path.join(self.config_dir, "jupyter_server_config.json")

    def start(self):
        """Start the password app."""
        from jupyter_server.auth.security import set_password

        set_password(config_file=self.config_file)
        self.log.info("Wrote hashed password to %s" % self.config_file)


def shutdown_server(server_info, timeout=5, log=None):
    """Shutdown a Jupyter server in a separate process.

    *server_info* should be a dictionary as produced by list_running_servers().

    Will first try to request shutdown using /api/shutdown .
    On Unix, if the server is still running after *timeout* seconds, it will
    send SIGTERM. After another timeout, it escalates to SIGKILL.

    Returns True if the server was stopped by any means, False if stopping it
    failed (on Windows).
    """

    url = server_info["url"]
    pid = server_info["pid"]
    try:
        shutdown_url = urljoin(url, "api/shutdown")
        if log:
            log.debug("POST request to %s", shutdown_url)
        fetch(
            shutdown_url,
            method="POST",
            body=b"",
            headers={"Authorization": "token " + server_info["token"]},
        )
    except Exception as ex:
        if not str(ex) == "Unknown URL scheme.":
            raise ex
        if log:
            log.debug("Was not a HTTP scheme. Treating as socket instead.")
            log.debug("POST request to %s", url)
        fetch(
            url,
            method="POST",
            body=b"",
            headers={"Authorization": "token " + server_info["token"]},
        )

    # Poll to see if it shut down.
    for _ in range(timeout * 10):
        if not check_pid(pid):
            if log:
                log.debug("Server PID %s is gone", pid)
            return True
        time.sleep(0.1)

    if sys.platform.startswith("win"):
        return False

    if log:
        log.debug("SIGTERM to PID %s", pid)
    os.kill(pid, signal.SIGTERM)

    # Poll to see if it shut down.
    for _ in range(timeout * 10):
        if not check_pid(pid):
            if log:
                log.debug("Server PID %s is gone", pid)
            return True
        time.sleep(0.1)

    if log:
        log.debug("SIGKILL to PID %s", pid)
    os.kill(pid, signal.SIGKILL)
    return True  # SIGKILL cannot be caught


class JupyterServerStopApp(JupyterApp):
    """An application to stop a Jupyter server."""

    version: str = __version__
    description: str = "Stop currently running Jupyter server for a given port"

    port = Integer(
        DEFAULT_JUPYTER_SERVER_PORT,
        config=True,
        help="Port of the server to be killed. Default %s" % DEFAULT_JUPYTER_SERVER_PORT,
    )

    sock = Unicode("", config=True, help="UNIX socket of the server to be killed.")

    def parse_command_line(self, argv=None):
        """Parse command line options."""
        super().parse_command_line(argv)
        if self.extra_args:
            try:
                self.port = int(self.extra_args[0])
            except ValueError:
                # self.extra_args[0] was not an int, so it must be a string (unix socket).
                self.sock = self.extra_args[0]

    def shutdown_server(self, server):
        """Shut down a server."""
        return shutdown_server(server, log=self.log)

    def _shutdown_or_exit(self, target_endpoint, server):
        """Handle a shutdown."""
        self.log.info("Shutting down server on %s..." % target_endpoint)
        if not self.shutdown_server(server):
            sys.exit("Could not stop server on %s" % target_endpoint)

    @staticmethod
    def _maybe_remove_unix_socket(socket_path):
        """Try to remove a socket path."""
        try:
            os.unlink(socket_path)
        except OSError:
            pass

    def start(self):
        """Start the server stop app."""
        info = self.log.info
        servers = list(list_running_servers(self.runtime_dir, log=self.log))
        if not servers:
            self.exit("There are no running servers (per %s)" % self.runtime_dir)
        for server in servers:
            if self.sock:
                sock = server.get("sock", None)
                if sock and sock == self.sock:
                    self._shutdown_or_exit(sock, server)
                    # Attempt to remove the UNIX socket after stopping.
                    self._maybe_remove_unix_socket(sock)
                    return
            elif self.port:
                port = server.get("port", None)
                if port == self.port:
                    self._shutdown_or_exit(port, server)
                    return
        current_endpoint = self.sock or self.port
        info(f"There is currently no server running on {current_endpoint}")
        info("Ports/sockets currently in use:")
        for server in servers:
            info(" - {}".format(server.get("sock") or server["port"]))
        self.exit(1)


class JupyterServerListApp(JupyterApp):
    """An application to list running Jupyter servers."""

    version: str = __version__
    description: str = _i18n("List currently running Jupyter servers.")

    flags = {
        "jsonlist": (
            {"JupyterServerListApp": {"jsonlist": True}},
            _i18n("Produce machine-readable JSON list output."),
        ),
        "json": (
            {"JupyterServerListApp": {"json": True}},
            _i18n("Produce machine-readable JSON object on each line of output."),
        ),
    }

    jsonlist = Bool(
        False,
        config=True,
        help=_i18n(
            "If True, the output will be a JSON list of objects, one per "
            "active Jupyer server, each with the details from the "
            "relevant server info file."
        ),
    )
    json = Bool(
        False,
        config=True,
        help=_i18n(
            "If True, each line of output will be a JSON object with the "
            "details from the server info file. For a JSON list output, "
            "see the JupyterServerListApp.jsonlist configuration value"
        ),
    )

    def start(self):
        """Start the server list application."""
        serverinfo_list = list(list_running_servers(self.runtime_dir, log=self.log))
        if self.jsonlist:
            print(json.dumps(serverinfo_list, indent=2))
        elif self.json:
            for serverinfo in serverinfo_list:
                print(json.dumps(serverinfo))
        else:
            print("Currently running servers:")
            for serverinfo in serverinfo_list:
                url = serverinfo["url"]
                if serverinfo.get("token"):
                    url = url + "?token=%s" % serverinfo["token"]
                print(url, "::", serverinfo["root_dir"])


# -----------------------------------------------------------------------------
# Aliases and Flags
# -----------------------------------------------------------------------------

flags = dict(base_flags)

flags["allow-root"] = (
    {"ServerApp": {"allow_root": True}},
    _i18n("Allow the server to be run from root user."),
)
flags["no-browser"] = (
    {"ServerApp": {"open_browser": False}, "ExtensionApp": {"open_browser": False}},
    _i18n("Prevent the opening of the default url in the browser."),
)
flags["debug"] = (
    {"ServerApp": {"log_level": "DEBUG"}, "ExtensionApp": {"log_level": "DEBUG"}},
    _i18n("Set debug level for the extension and underlying server applications."),
)
flags["autoreload"] = (
    {"ServerApp": {"autoreload": True}},
    """Autoreload the webapp
    Enable reloading of the tornado webapp and all imported Python packages
    when any changes are made to any Python src files in server or
    extensions.
    """,
)


# Add notebook manager flags
flags.update(
    boolean_flag(
        "script",
        "FileContentsManager.save_script",
        "DEPRECATED, IGNORED",
        "DEPRECATED, IGNORED",
    )
)

aliases = dict(base_aliases)

aliases.update(
    {
        "ip": "ServerApp.ip",
        "port": "ServerApp.port",
        "port-retries": "ServerApp.port_retries",
        "sock": "ServerApp.sock",
        "sock-mode": "ServerApp.sock_mode",
        "transport": "KernelManager.transport",
        "keyfile": "ServerApp.keyfile",
        "certfile": "ServerApp.certfile",
        "client-ca": "ServerApp.client_ca",
        "notebook-dir": "ServerApp.root_dir",
        "preferred-dir": "ServerApp.preferred_dir",
        "browser": "ServerApp.browser",
        "pylab": "ServerApp.pylab",
        "gateway-url": "GatewayClient.url",
    }
)

# -----------------------------------------------------------------------------
# ServerApp
# -----------------------------------------------------------------------------


class ServerApp(JupyterApp):
    """The Jupyter Server application class."""

    name = "jupyter-server"
    version: str = __version__
    description: str = _i18n(
        """The Jupyter Server.

    This launches a Tornado-based Jupyter Server."""
    )
    examples = _examples

    flags = Dict(flags)  # type:ignore[assignment]
    aliases = Dict(aliases)  # type:ignore[assignment]

    classes = [
        KernelManager,
        Session,
        MappingKernelManager,
        KernelSpecManager,
        AsyncMappingKernelManager,
        ContentsManager,
        FileContentsManager,
        AsyncContentsManager,
        AsyncFileContentsManager,
        NotebookNotary,
        GatewayMappingKernelManager,
        GatewayKernelSpecManager,
        GatewaySessionManager,
        GatewayWebSocketConnection,
        GatewayClient,
        Authorizer,
        EventLogger,
        ZMQChannelsWebsocketConnection,
    ]

    subcommands: dict[str, t.Any] = {
        "list": (
            JupyterServerListApp,
            JupyterServerListApp.description.splitlines()[0],
        ),
        "stop": (
            JupyterServerStopApp,
            JupyterServerStopApp.description.splitlines()[0],
        ),
        "password": (
            JupyterPasswordApp,
            JupyterPasswordApp.description.splitlines()[0],
        ),
        "extension": (
            ServerExtensionApp,
            ServerExtensionApp.description.splitlines()[0],
        ),
    }

    # A list of services whose handlers will be exposed.
    # Subclasses can override this list to
    # expose a subset of these handlers.
    default_services = (
        "api",
        "auth",
        "config",
        "contents",
        "files",
        "kernels",
        "kernelspecs",
        "nbconvert",
        "security",
        "sessions",
        "shutdown",
        "view",
        "events",
    )

    _log_formatter_cls = LogFormatter  # type:ignore[assignment]
    _stopping = Bool(False, help="Signal that we've begun stopping.")

    @default("log_level")
    def _default_log_level(self) -> int:
        return logging.INFO

    @default("log_format")
    def _default_log_format(self) -> str:
        """override default log format to include date & time"""
        return (
            "%(color)s[%(levelname)1.1s %(asctime)s.%(msecs).03d %(name)s]%(end_color)s %(message)s"
        )

    # file to be opened in the Jupyter server
    file_to_run = Unicode("", help="Open the named file when the application is launched.").tag(
        config=True
    )

    file_url_prefix = Unicode(
        "notebooks", help="The URL prefix where files are opened directly."
    ).tag(config=True)

    # Network related information
    allow_origin = Unicode(
        "",
        config=True,
        help="""Set the Access-Control-Allow-Origin header

        Use '*' to allow any origin to access your server.

        Takes precedence over allow_origin_pat.
        """,
    )

    allow_origin_pat = Unicode(
        "",
        config=True,
        help="""Use a regular expression for the Access-Control-Allow-Origin header

        Requests from an origin matching the expression will get replies with:

            Access-Control-Allow-Origin: origin

        where `origin` is the origin of the request.

        Ignored if allow_origin is set.
        """,
    )

    allow_credentials = Bool(
        False,
        config=True,
        help=_i18n("Set the Access-Control-Allow-Credentials: true header"),
    )

    allow_root = Bool(
        False,
        config=True,
        help=_i18n("Whether to allow the user to run the server as root."),
    )

    autoreload = Bool(
        False,
        config=True,
        help=_i18n("Reload the webapp when changes are made to any Python src files."),
    )

    default_url = Unicode("/", config=True, help=_i18n("The default URL to redirect to from `/`"))

    ip = Unicode(
        "localhost",
        config=True,
        help=_i18n("The IP address the Jupyter server will listen on."),
    )

    @default("ip")
    def _default_ip(self) -> str:
        """Return localhost if available, 127.0.0.1 otherwise.

        On some (horribly broken) systems, localhost cannot be bound.
        """
        s = socket.socket()
        try:
            s.bind(("localhost", 0))
        except OSError as e:
            self.log.warning(
                _i18n("Cannot bind to localhost, using 127.0.0.1 as default ip\n%s"), e
            )
            return "127.0.0.1"
        else:
            s.close()
            return "localhost"

    @validate("ip")
    def _validate_ip(self, proposal: t.Any) -> str:
        value = t.cast(str, proposal["value"])
        if value == "*":
            value = ""
        return value

    custom_display_url = Unicode(
        "",
        config=True,
        help=_i18n(
            """Override URL shown to users.

        Replace actual URL, including protocol, address, port and base URL,
        with the given value when displaying URL to the users. Do not change
        the actual connection URL. If authentication token is enabled, the
        token is added to the custom URL automatically.

        This option is intended to be used when the URL to display to the user
        cannot be determined reliably by the Jupyter server (proxified
        or containerized setups for example)."""
        ),
    )

    port_env = "JUPYTER_PORT"
    port_default_value = DEFAULT_JUPYTER_SERVER_PORT

    port = Integer(
        config=True,
        help=_i18n("The port the server will listen on (env: JUPYTER_PORT)."),
    )

    @default("port")
    def _port_default(self) -> int:
        return int(os.getenv(self.port_env, self.port_default_value))

    port_retries_env = "JUPYTER_PORT_RETRIES"
    port_retries_default_value = 50
    port_retries = Integer(
        port_retries_default_value,
        config=True,
        help=_i18n(
            "The number of additional ports to try if the specified port is not "
            "available (env: JUPYTER_PORT_RETRIES)."
        ),
    )

    @default("port_retries")
    def _port_retries_default(self) -> int:
        return int(os.getenv(self.port_retries_env, self.port_retries_default_value))

    sock = Unicode("", config=True, help="The UNIX socket the Jupyter server will listen on.")

    sock_mode = Unicode(
        "0600",
        config=True,
        help="The permissions mode for UNIX socket creation (default: 0600).",
    )

    @validate("sock_mode")
    def _validate_sock_mode(self, proposal: t.Any) -> t.Any:
        value = proposal["value"]
        try:
            converted_value = int(value.encode(), 8)
            assert all(
                (
                    # Ensure the mode is at least user readable/writable.
                    bool(converted_value & stat.S_IRUSR),
                    bool(converted_value & stat.S_IWUSR),
                    # And isn't out of bounds.
                    converted_value <= 2**12,
                )
            )
        except ValueError as e:
            raise TraitError(
                'invalid --sock-mode value: %s, please specify as e.g. "0600"' % value
            ) from e
        except AssertionError as e:
            raise TraitError(
                "invalid --sock-mode value: %s, must have u+rw (0600) at a minimum" % value
            ) from e
        return value

    certfile = Unicode(
        "",
        config=True,
        help=_i18n("""The full path to an SSL/TLS certificate file."""),
    )

    keyfile = Unicode(
        "",
        config=True,
        help=_i18n("""The full path to a private key file for usage with SSL/TLS."""),
    )

    client_ca = Unicode(
        "",
        config=True,
        help=_i18n(
            """The full path to a certificate authority certificate for SSL/TLS client authentication."""
        ),
    )

    cookie_secret_file = Unicode(
        config=True, help=_i18n("""The file where the cookie secret is stored.""")
    )

    @default("cookie_secret_file")
    def _default_cookie_secret_file(self) -> str:
        return os.path.join(self.runtime_dir, "jupyter_cookie_secret")

    cookie_secret = Bytes(
        b"",
        config=True,
        help="""The random bytes used to secure cookies.
        By default this is generated on first start of the server and persisted across server
        sessions by writing the cookie secret into the `cookie_secret_file` file.
        When using an executable config file you can override this to be random at each server restart.

        Note: Cookie secrets should be kept private, do not share config files with
        cookie_secret stored in plaintext (you can read the value from a file).
        """,
    )

    @default("cookie_secret")
    def _default_cookie_secret(self) -> bytes:
        if os.path.exists(self.cookie_secret_file):
            with open(self.cookie_secret_file, "rb") as f:
                key = f.read()
        else:
            key = encodebytes(os.urandom(32))
            self._write_cookie_secret_file(key)
        h = hmac.new(key, digestmod=hashlib.sha256)
        h.update(self.password.encode())
        return h.digest()

    def _write_cookie_secret_file(self, secret: bytes) -> None:
        """write my secret to my secret_file"""
        self.log.info(_i18n("Writing Jupyter server cookie secret to %s"), self.cookie_secret_file)
        try:
            with secure_write(self.cookie_secret_file, True) as f:
                f.write(secret)
        except OSError as e:
            self.log.error(
                _i18n("Failed to write cookie secret to %s: %s"),
                self.cookie_secret_file,
                e,
            )

    _token_set = False

    token = Unicode("<DEPRECATED>", help=_i18n("""DEPRECATED. Use IdentityProvider.token""")).tag(
        config=True
    )

    @observe("token")
    def _deprecated_token(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "IdentityProvider")

    @default("token")
    def _deprecated_token_access(self) -> str:
        warnings.warn(
            "ServerApp.token config is deprecated in jupyter-server 2.0. Use IdentityProvider.token",
            DeprecationWarning,
            stacklevel=3,
        )
        return self.identity_provider.token

    min_open_files_limit = Integer(
        config=True,
        help="""
        Gets or sets a lower bound on the open file handles process resource
        limit. This may need to be increased if you run into an
        OSError: [Errno 24] Too many open files.
        This is not applicable when running on Windows.
        """,
        allow_none=True,
    )

    @default("min_open_files_limit")
    def _default_min_open_files_limit(self) -> t.Optional[int]:
        if resource is None:
            # Ignoring min_open_files_limit because the limit cannot be adjusted (for example, on Windows)
            return None  # type:ignore[unreachable]

        soft, hard = resource.getrlimit(resource.RLIMIT_NOFILE)

        default_soft = 4096
        if hard >= default_soft:
            return default_soft

        self.log.debug(
            "Default value for min_open_files_limit is ignored (hard=%r, soft=%r)",
            hard,
            soft,
        )

        return soft

    max_body_size = Integer(
        512 * 1024 * 1024,
        config=True,
        help="""
        Sets the maximum allowed size of the client request body, specified in
        the Content-Length request header field. If the size in a request
        exceeds the configured value, a malformed HTTP message is returned to
        the client.

        Note: max_body_size is applied even in streaming mode.
        """,
    )

    max_buffer_size = Integer(
        512 * 1024 * 1024,
        config=True,
        help="""
        Gets or sets the maximum amount of memory, in bytes, that is allocated
        for use by the buffer manager.
        """,
    )

    password = Unicode(
        "",
        config=True,
        help="""DEPRECATED in 2.0. Use PasswordIdentityProvider.hashed_password""",
    )

    password_required = Bool(
        False,
        config=True,
        help="""DEPRECATED in 2.0. Use PasswordIdentityProvider.password_required""",
    )

    allow_password_change = Bool(
        True,
        config=True,
        help="""DEPRECATED in 2.0. Use PasswordIdentityProvider.allow_password_change""",
    )

    def _warn_deprecated_config(
        self, change: t.Any, clsname: str, new_name: t.Optional[str] = None
    ) -> None:
        """Warn on deprecated config."""
        if new_name is None:
            new_name = change.name
        if clsname not in self.config or new_name not in self.config[clsname]:
            # Deprecated config used, new config not used.
            # Use deprecated config, warn about new name.
            self.log.warning(
                f"ServerApp.{change.name} config is deprecated in 2.0. Use {clsname}.{new_name}."
            )
            self.config[clsname][new_name] = change.new
        # Deprecated config used, new config also used.
        # Warn only if the values differ.
        # If the values are the same, assume intentional backward-compatible config.
        elif self.config[clsname][new_name] != change.new:
            self.log.warning(
                f"Ignoring deprecated ServerApp.{change.name} config. Using {clsname}.{new_name}."
            )

    @observe("password")
    def _deprecated_password(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "PasswordIdentityProvider", new_name="hashed_password")

    @observe("password_required", "allow_password_change")
    def _deprecated_password_config(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "PasswordIdentityProvider")

    disable_check_xsrf = Bool(
        False,
        config=True,
        help="""Disable cross-site-request-forgery protection

        Jupyter server includes protection from cross-site request forgeries,
        requiring API requests to either:

        - originate from pages served by this server (validated with XSRF cookie and token), or
        - authenticate with a token

        Some anonymous compute resources still desire the ability to run code,
        completely without authentication.
        These services can disable all authentication and security checks,
        with the full knowledge of what that implies.
        """,
    )

    _allow_unauthenticated_access_env = "JUPYTER_SERVER_ALLOW_UNAUTHENTICATED_ACCESS"

    allow_unauthenticated_access = Bool(
        True,
        config=True,
        help=f"""Allow unauthenticated access to endpoints without authentication rule.

        When set to `True` (default in jupyter-server 2.0, subject to change
        in the future), any request to an endpoint without an authentication rule
        (either `@tornado.web.authenticated`, or `@allow_unauthenticated`)
        will be permitted, regardless of whether user has logged in or not.

        When set to `False`, logging in will be required for access to each endpoint,
        excluding the endpoints marked with `@allow_unauthenticated` decorator.

        This option can be configured using `{_allow_unauthenticated_access_env}`
        environment variable: any non-empty value other than "true" and "yes" will
        prevent unauthenticated access to endpoints without `@allow_unauthenticated`.
        """,
    )

    @default("allow_unauthenticated_access")
    def _allow_unauthenticated_access_default(self):
        if os.getenv(self._allow_unauthenticated_access_env):
            return os.environ[self._allow_unauthenticated_access_env].lower() in ["true", "yes"]
        return True

    allow_remote_access = Bool(
        config=True,
        help="""Allow requests where the Host header doesn't point to a local server

       By default, requests get a 403 forbidden response if the 'Host' header
       shows that the browser thinks it's on a non-local domain.
       Setting this option to True disables this check.

       This protects against 'DNS rebinding' attacks, where a remote web server
       serves you a page and then changes its DNS to send later requests to a
       local IP, bypassing same-origin checks.

       Local IP addresses (such as 127.0.0.1 and ::1) are allowed as local,
       along with hostnames configured in local_hostnames.
       """,
    )

    @default("allow_remote_access")
    def _default_allow_remote(self) -> bool:
        """Disallow remote access if we're listening only on loopback addresses"""

        # if blank, self.ip was configured to "*" meaning bind to all interfaces,
        # see _valdate_ip
        if self.ip == "":
            return True

        try:
            addr = ipaddress.ip_address(self.ip)
        except ValueError:
            # Address is a hostname
            for info in socket.getaddrinfo(self.ip, self.port, 0, socket.SOCK_STREAM):
                addr = info[4][0]  # type:ignore[assignment]

                try:
                    parsed = ipaddress.ip_address(addr.split("%")[0])  # type:ignore[union-attr]
                except ValueError:
                    self.log.warning("Unrecognised IP address: %r", addr)
                    continue

                # Macs map localhost to 'fe80::1%lo0', a link local address
                # scoped to the loopback interface. For now, we'll assume that
                # any scoped link-local address is effectively local.
                if not (
                    parsed.is_loopback or (("%" in addr) and parsed.is_link_local)  # type:ignore[operator]
                ):
                    return True
            return False
        else:
            return not addr.is_loopback

    use_redirect_file = Bool(
        True,
        config=True,
        help="""Disable launching browser by redirect file
     For versions of notebook > 5.7.2, a security feature measure was added that
     prevented the authentication token used to launch the browser from being visible.
     This feature makes it difficult for other users on a multi-user system from
     running code in your Jupyter session as you.
     However, some environments (like Windows Subsystem for Linux (WSL) and Chromebooks),
     launching a browser using a redirect file can lead the browser failing to load.
     This is because of the difference in file structures/paths between the runtime and
     the browser.

     Disabling this setting to False will disable this behavior, allowing the browser
     to launch by using a URL and visible token (as before).
     """,
    )

    local_hostnames = List(
        Unicode(),
        ["localhost"],
        config=True,
        help="""Hostnames to allow as local when allow_remote_access is False.

       Local IP addresses (such as 127.0.0.1 and ::1) are automatically accepted
       as local as well.
       """,
    )

    open_browser = Bool(
        False,
        config=True,
        help="""Whether to open in a browser after starting.
                        The specific browser used is platform dependent and
                        determined by the python standard library `webbrowser`
                        module, unless it is overridden using the --browser
                        (ServerApp.browser) configuration option.
                        """,
    )

    browser = Unicode(
        "",
        config=True,
        help="""Specify what command to use to invoke a web
                      browser when starting the server. If not specified, the
                      default browser will be determined by the `webbrowser`
                      standard library module, which allows setting of the
                      BROWSER environment variable to override it.
                      """,
    )

    webbrowser_open_new = Integer(
        2,
        config=True,
        help=_i18n(
            """Specify where to open the server on startup. This is the
        `new` argument passed to the standard library method `webbrowser.open`.
        The behaviour is not guaranteed, but depends on browser support. Valid
        values are:

         - 2 opens a new tab,
         - 1 opens a new window,
         - 0 opens in an existing window.

        See the `webbrowser.open` documentation for details.
        """
        ),
    )

    tornado_settings = Dict(
        config=True,
        help=_i18n(
            "Supply overrides for the tornado.web.Application that the Jupyter server uses."
        ),
    )

    websocket_compression_options = Any(
        None,
        config=True,
        help=_i18n(
            """
        Set the tornado compression options for websocket connections.

        This value will be returned from :meth:`WebSocketHandler.get_compression_options`.
        None (default) will disable compression.
        A dict (even an empty one) will enable compression.

        See the tornado docs for WebSocketHandler.get_compression_options for details.
        """
        ),
    )
    terminado_settings = Dict(
        Union([List(), Unicode()]),
        config=True,
        help=_i18n('Supply overrides for terminado. Currently only supports "shell_command".'),
    )

    cookie_options = Dict(
        config=True,
        help=_i18n("DEPRECATED. Use IdentityProvider.cookie_options"),
    )
    get_secure_cookie_kwargs = Dict(
        config=True,
        help=_i18n("DEPRECATED. Use IdentityProvider.get_secure_cookie_kwargs"),
    )

    @observe("cookie_options", "get_secure_cookie_kwargs")
    def _deprecated_cookie_config(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "IdentityProvider")

    ssl_options = Dict(
        allow_none=True,
        config=True,
        help=_i18n(
            """Supply SSL options for the tornado HTTPServer.
            See the tornado docs for details."""
        ),
    )

    jinja_environment_options = Dict(
        config=True,
        help=_i18n("Supply extra arguments that will be passed to Jinja environment."),
    )

    jinja_template_vars = Dict(
        config=True,
        help=_i18n("Extra variables to supply to jinja templates when rendering."),
    )

    base_url = Unicode(
        "/",
        config=True,
        help="""The base URL for the Jupyter server.

                       Leading and trailing slashes can be omitted,
                       and will automatically be added.
                       """,
    )

    @validate("base_url")
    def _update_base_url(self, proposal: t.Any) -> str:
        value = t.cast(str, proposal["value"])
        if not value.startswith("/"):
            value = "/" + value
        if not value.endswith("/"):
            value = value + "/"
        return value

    extra_static_paths = List(
        Unicode(),
        config=True,
        help="""Extra paths to search for serving static files.

        This allows adding javascript/css to be available from the Jupyter server machine,
        or overriding individual files in the IPython""",
    )

    @property
    def static_file_path(self) -> list[str]:
        """return extra paths + the default location"""
        return [*self.extra_static_paths, DEFAULT_STATIC_FILES_PATH]

    static_custom_path = List(Unicode(), help=_i18n("""Path to search for custom.js, css"""))

    @default("static_custom_path")
    def _default_static_custom_path(self) -> list[str]:
        return [os.path.join(d, "custom") for d in (self.config_dir, DEFAULT_STATIC_FILES_PATH)]

    extra_template_paths = List(
        Unicode(),
        config=True,
        help=_i18n(
            """Extra paths to search for serving jinja templates.

        Can be used to override templates from jupyter_server.templates."""
        ),
    )

    @property
    def template_file_path(self) -> list[str]:
        """return extra paths + the default locations"""
        return self.extra_template_paths + DEFAULT_TEMPLATE_PATH_LIST

    extra_services = List(
        Unicode(),
        config=True,
        help=_i18n(
            """handlers that should be loaded at higher priority than the default services"""
        ),
    )

    websocket_url = Unicode(
        "",
        config=True,
        help="""The base URL for websockets,
        if it differs from the HTTP server (hint: it almost certainly doesn't).

        Should be in the form of an HTTP origin: ws[s]://hostname[:port]
        """,
    )

    quit_button = Bool(
        True,
        config=True,
        help="""If True, display controls to shut down the Jupyter server, such as menu items or buttons.""",
    )

    contents_manager_class = Type(
        default_value=AsyncLargeFileManager,
        klass=ContentsManager,
        config=True,
        help=_i18n("The content manager class to use."),
    )

    kernel_manager_class = Type(
        klass=MappingKernelManager,
        config=True,
        help=_i18n("The kernel manager class to use."),
    )

    @default("kernel_manager_class")
    def _default_kernel_manager_class(self) -> t.Union[str, type[AsyncMappingKernelManager]]:
        if self.gateway_config.gateway_enabled:
            return "jupyter_server.gateway.managers.GatewayMappingKernelManager"
        return AsyncMappingKernelManager

    session_manager_class = Type(
        config=True,
        help=_i18n("The session manager class to use."),
    )

    @default("session_manager_class")
    def _default_session_manager_class(self) -> t.Union[str, type[SessionManager]]:
        if self.gateway_config.gateway_enabled:
            return "jupyter_server.gateway.managers.GatewaySessionManager"
        return SessionManager

    kernel_websocket_connection_class = Type(
        klass=BaseKernelWebsocketConnection,
        config=True,
        help=_i18n("The kernel websocket connection class to use."),
    )

    @default("kernel_websocket_connection_class")
    def _default_kernel_websocket_connection_class(
        self,
    ) -> t.Union[str, type[ZMQChannelsWebsocketConnection]]:
        if self.gateway_config.gateway_enabled:
            return "jupyter_server.gateway.connections.GatewayWebSocketConnection"
        return ZMQChannelsWebsocketConnection

    websocket_ping_interval = Integer(
        config=True,
        help="""
            Configure the websocket ping interval in seconds.

            Websockets are long-lived connections that are used by some Jupyter
            Server extensions.

            Periodic pings help to detect disconnected clients and keep the
            connection active. If this is set to None, then no pings will be
            performed.

            When a ping is sent, the client has ``websocket_ping_timeout``
            seconds to respond. If no response is received within this period,
            the connection will be closed from the server side.
        """,
    )
    websocket_ping_timeout = Integer(
        config=True,
        help="""
            Configure the websocket ping timeout in seconds.

            See ``websocket_ping_interval`` for details.
        """,
    )

    config_manager_class = Type(
        default_value=ConfigManager,
        config=True,
        help=_i18n("The config manager class to use"),
    )

    kernel_spec_manager = Instance(KernelSpecManager, allow_none=True)

    kernel_spec_manager_class = Type(
        config=True,
        help="""
        The kernel spec manager class to use. Should be a subclass
        of `jupyter_client.kernelspec.KernelSpecManager`.

        The Api of KernelSpecManager is provisional and might change
        without warning between this version of Jupyter and the next stable one.
        """,
    )

    @default("kernel_spec_manager_class")
    def _default_kernel_spec_manager_class(self) -> t.Union[str, type[KernelSpecManager]]:
        if self.gateway_config.gateway_enabled:
            return "jupyter_server.gateway.managers.GatewayKernelSpecManager"
        return KernelSpecManager

    login_handler_class = Type(
        default_value=LoginHandler,
        klass=web.RequestHandler,
        allow_none=True,
        config=True,
        help=_i18n("The login handler class to use."),
    )

    logout_handler_class = Type(
        default_value=LogoutHandler,
        klass=web.RequestHandler,
        allow_none=True,
        config=True,
        help=_i18n("The logout handler class to use."),
    )
    # TODO: detect deprecated login handler config

    authorizer_class = Type(
        default_value=AllowAllAuthorizer,
        klass=Authorizer,
        config=True,
        help=_i18n("The authorizer class to use."),
    )

    identity_provider_class = Type(
        default_value=PasswordIdentityProvider,
        klass=IdentityProvider,
        config=True,
        help=_i18n("The identity provider class to use."),
    )

    trust_xheaders = Bool(
        False,
        config=True,
        help=(
            _i18n(
                "Whether to trust or not X-Scheme/X-Forwarded-Proto and X-Real-Ip/X-Forwarded-For headers"
                "sent by the upstream reverse proxy. Necessary if the proxy handles SSL"
            )
        ),
    )

    event_logger = Instance(
        EventLogger,
        allow_none=True,
        help="An EventLogger for emitting structured event data from Jupyter Server and extensions.",
    )

    info_file = Unicode()

    @default("info_file")
    def _default_info_file(self) -> str:
        info_file = "jpserver-%s.json" % os.getpid()
        return os.path.join(self.runtime_dir, info_file)

    no_browser_open_file = Bool(
        False, help="If True, do not write redirect HTML file disk, or show in messages."
    )

    browser_open_file = Unicode()

    @default("browser_open_file")
    def _default_browser_open_file(self) -> str:
        basename = "jpserver-%s-open.html" % os.getpid()
        return os.path.join(self.runtime_dir, basename)

    browser_open_file_to_run = Unicode()

    @default("browser_open_file_to_run")
    def _default_browser_open_file_to_run(self) -> str:
        basename = "jpserver-file-to-run-%s-open.html" % os.getpid()
        return os.path.join(self.runtime_dir, basename)

    pylab = Unicode(
        "disabled",
        config=True,
        help=_i18n(
            """
        DISABLED: use %pylab or %matplotlib in the notebook to enable matplotlib.
        """
        ),
    )

    @observe("pylab")
    def _update_pylab(self, change: t.Any) -> None:
        """when --pylab is specified, display a warning and exit"""
        backend = " %s" % change["new"] if change["new"] != "warn" else ""
        self.log.error(
            _i18n("Support for specifying --pylab on the command line has been removed.")
        )
        self.log.error(
            _i18n("Please use `%pylab{0}` or `%matplotlib{0}` in the notebook itself.").format(
                backend
            )
        )
        self.exit(1)

    notebook_dir = Unicode(config=True, help=_i18n("DEPRECATED, use root_dir."))

    @observe("notebook_dir")
    def _update_notebook_dir(self, change: t.Any) -> None:
        if self._root_dir_set:
            # only use deprecated config if new config is not set
            return
        self.log.warning(_i18n("notebook_dir is deprecated, use root_dir"))
        self.root_dir = change["new"]

    external_connection_dir = Unicode(
        None,
        allow_none=True,
        config=True,
        help=_i18n(
            "The directory to look at for external kernel connection files, if allow_external_kernels is True. "
            "Defaults to Jupyter runtime_dir/external_kernels. "
            "Make sure that this directory is not filled with left-over connection files, "
            "that could result in unnecessary kernel manager creations."
        ),
    )

    allow_external_kernels = Bool(
        False,
        config=True,
        help=_i18n(
            "Whether or not to allow external kernels, whose connection files are placed in external_connection_dir."
        ),
    )

    root_dir = Unicode(config=True, help=_i18n("The directory to use for notebooks and kernels."))
    _root_dir_set = False

    @default("root_dir")
    def _default_root_dir(self) -> str:
        if self.file_to_run:
            self._root_dir_set = True
            return os.path.dirname(os.path.abspath(self.file_to_run))
        else:
            return os.getcwd()

    def _normalize_dir(self, value: str) -> str:
        """Normalize a directory."""
        # Strip any trailing slashes
        # *except* if it's root
        _, path = os.path.splitdrive(value)
        if path == os.sep:
            return value
        value = value.rstrip(os.sep)
        if not os.path.isabs(value):
            # If we receive a non-absolute path, make it absolute.
            value = os.path.abspath(value)
        return value

    @validate("root_dir")
    def _root_dir_validate(self, proposal: t.Any) -> str:
        value = self._normalize_dir(proposal["value"])
        if not os.path.isdir(value):
            raise TraitError(trans.gettext("No such directory: '%r'") % value)
        return value

    @observe("root_dir")
    def _root_dir_changed(self, change: t.Any) -> None:
        # record that root_dir is set,
        # which affects loading of deprecated notebook_dir
        self._root_dir_set = True

    preferred_dir = Unicode(
        config=True,
        help=trans.gettext(
            "Preferred starting directory to use for notebooks and kernels. ServerApp.preferred_dir is deprecated in jupyter-server 2.0. Use FileContentsManager.preferred_dir instead"
        ),
    )

    @default("preferred_dir")
    def _default_prefered_dir(self) -> str:
        return self.root_dir

    @validate("preferred_dir")
    def _preferred_dir_validate(self, proposal: t.Any) -> str:
        value = self._normalize_dir(proposal["value"])
        if not os.path.isdir(value):
            raise TraitError(trans.gettext("No such preferred dir: '%r'") % value)
        return value

    @observe("server_extensions")
    def _update_server_extensions(self, change: t.Any) -> None:
        self.log.warning(_i18n("server_extensions is deprecated, use jpserver_extensions"))
        self.server_extensions = change["new"]

    jpserver_extensions = Dict(
        default_value={},
        value_trait=Bool(),
        config=True,
        help=(
            _i18n(
                "Dict of Python modules to load as Jupyter server extensions."
                "Entry values can be used to enable and disable the loading of"
                "the extensions. The extensions will be loaded in alphabetical "
                "order."
            )
        ),
    )

    reraise_server_extension_failures = Bool(
        False,
        config=True,
        help=_i18n("Reraise exceptions encountered loading server extensions?"),
    )

    kernel_ws_protocol = Unicode(
        allow_none=True,
        config=True,
        help=_i18n("DEPRECATED. Use ZMQChannelsWebsocketConnection.kernel_ws_protocol"),
    )

    @observe("kernel_ws_protocol")
    def _deprecated_kernel_ws_protocol(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "ZMQChannelsWebsocketConnection")

    limit_rate = Bool(
        allow_none=True,
        config=True,
        help=_i18n("DEPRECATED. Use ZMQChannelsWebsocketConnection.limit_rate"),
    )

    @observe("limit_rate")
    def _deprecated_limit_rate(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "ZMQChannelsWebsocketConnection")

    iopub_msg_rate_limit = Float(
        allow_none=True,
        config=True,
        help=_i18n("DEPRECATED. Use ZMQChannelsWebsocketConnection.iopub_msg_rate_limit"),
    )

    @observe("iopub_msg_rate_limit")
    def _deprecated_iopub_msg_rate_limit(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "ZMQChannelsWebsocketConnection")

    iopub_data_rate_limit = Float(
        allow_none=True,
        config=True,
        help=_i18n("DEPRECATED. Use ZMQChannelsWebsocketConnection.iopub_data_rate_limit"),
    )

    @observe("iopub_data_rate_limit")
    def _deprecated_iopub_data_rate_limit(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "ZMQChannelsWebsocketConnection")

    rate_limit_window = Float(
        allow_none=True,
        config=True,
        help=_i18n("DEPRECATED. Use ZMQChannelsWebsocketConnection.rate_limit_window"),
    )

    @observe("rate_limit_window")
    def _deprecated_rate_limit_window(self, change: t.Any) -> None:
        self._warn_deprecated_config(change, "ZMQChannelsWebsocketConnection")

    shutdown_no_activity_timeout = Integer(
        0,
        config=True,
        help=(
            "Shut down the server after N seconds with no kernels"
            "running and no activity. "
            "This can be used together with culling idle kernels "
            "(MappingKernelManager.cull_idle_timeout) to "
            "shutdown the Jupyter server when it's not in use. This is not "
            "precisely timed: it may shut down up to a minute later. "
            "0 (the default) disables this automatic shutdown."
        ),
    )

    terminals_enabled = Bool(
        config=True,
        help=_i18n(
            """Set to False to disable terminals.

         This does *not* make the server more secure by itself.
         Anything the user can in a terminal, they can also do in a notebook.

         Terminals may also be automatically disabled if the terminado package
         is not available.
         """
        ),
    )

    @default("terminals_enabled")
    def _default_terminals_enabled(self) -> bool:
        return True

    authenticate_prometheus = Bool(
        True,
        help=""""
        Require authentication to access prometheus metrics.
        """,
        config=True,
    )

    static_immutable_cache = List(
        Unicode(),
        help="""
        Paths to set up static files as immutable.

        This allow setting up the cache control of static files as immutable.
        It should be used for static file named with a hash for instance.
        """,
        config=True,
    )

    _starter_app = Instance(
        default_value=None,
        allow_none=True,
        klass="jupyter_server.extension.application.ExtensionApp",
    )

    @property
    def starter_app(self) -> t.Any:
        """Get the Extension that started this server."""
        return self._starter_app

    def parse_command_line(self, argv: t.Optional[list[str]] = None) -> None:
        """Parse the command line options."""
        super().parse_command_line(argv)

        if self.extra_args:
            arg0 = self.extra_args[0]
            f = os.path.abspath(arg0)
            self.argv.remove(arg0)
            if not os.path.exists(f):
                self.log.critical(_i18n("No such file or directory: %s"), f)
                self.exit(1)

            # Use config here, to ensure that it takes higher priority than
            # anything that comes from the config dirs.
            c = Config()
            if os.path.isdir(f):
                c.ServerApp.root_dir = f
            elif os.path.isfile(f):
                c.ServerApp.file_to_run = f
            self.update_config(c)

    def init_configurables(self) -> None:
        """Initialize configurables."""
        # If gateway server is configured, replace appropriate managers to perform redirection.  To make
        # this determination, instantiate the GatewayClient config singleton.
        self.gateway_config = GatewayClient.instance(parent=self)

        if not issubclass(
            self.kernel_manager_class,
            AsyncMappingKernelManager,
        ):
            warnings.warn(
                "The synchronous MappingKernelManager class is deprecated and will not be supported in Jupyter Server 3.0",
                DeprecationWarning,
                stacklevel=2,
            )

        if not issubclass(
            self.contents_manager_class,
            AsyncContentsManager,
        ):
            warnings.warn(
                "The synchronous ContentsManager classes are deprecated and will not be supported in Jupyter Server 3.0",
                DeprecationWarning,
                stacklevel=2,
            )

        self.kernel_spec_manager = self.kernel_spec_manager_class(
            parent=self,
        )

        kwargs = {
            "parent": self,
            "log": self.log,
            "connection_dir": self.runtime_dir,
            "kernel_spec_manager": self.kernel_spec_manager,
        }
        if jupyter_client.version_info > (8, 3, 0):  # type:ignore[attr-defined]
            if self.allow_external_kernels:
                external_connection_dir = self.external_connection_dir
                if external_connection_dir is None:
                    external_connection_dir = str(Path(self.runtime_dir) / "external_kernels")
                kwargs["external_connection_dir"] = external_connection_dir
        elif self.allow_external_kernels:
            self.log.warning(
                "Although allow_external_kernels=True, external kernels are not supported "
                "because jupyter-client's version does not allow them (should be >8.3.0)."
            )

        self.kernel_manager = self.kernel_manager_class(**kwargs)
        self.contents_manager = self.contents_manager_class(
            parent=self,
            log=self.log,
        )
        # Trigger a default/validation here explicitly while we still support the
        # deprecated trait on ServerApp (FIXME remove when deprecation finalized)
        self.contents_manager.preferred_dir  # noqa: B018
        self.session_manager = self.session_manager_class(
            parent=self,
            log=self.log,
            kernel_manager=self.kernel_manager,
            contents_manager=self.contents_manager,
        )
        self.config_manager = self.config_manager_class(
            parent=self,
            log=self.log,
        )
        identity_provider_kwargs = {"parent": self, "log": self.log}

        if (
            self.login_handler_class is not LoginHandler
            and self.identity_provider_class is PasswordIdentityProvider
        ):
            # default identity provider, non-default LoginHandler
            # this indicates legacy custom LoginHandler config.
            # enable LegacyIdentityProvider, which defers to the LoginHandler for pre-2.0 behavior.
            self.identity_provider_class = LegacyIdentityProvider
            self.log.warning(
                f"Customizing authentication via ServerApp.login_handler_class={self.login_handler_class}"
                " is deprecated in Jupyter Server 2.0."
                " Use ServerApp.identity_provider_class."
                " Falling back on legacy authentication.",
            )
            identity_provider_kwargs["login_handler_class"] = self.login_handler_class
            if self.logout_handler_class:
                identity_provider_kwargs["logout_handler_class"] = self.logout_handler_class
        elif self.login_handler_class is not LoginHandler:
            # non-default login handler ignored because also explicitly set identity provider
            self.log.warning(
                f"Ignoring deprecated config ServerApp.login_handler_class={self.login_handler_class}."
                " Superseded by ServerApp.identity_provider_class={self.identity_provider_class}."
            )
        self.identity_provider = self.identity_provider_class(**identity_provider_kwargs)

        if self.identity_provider_class is LegacyIdentityProvider:
            # legacy config stored the password in tornado_settings
            self.tornado_settings["password"] = self.identity_provider.hashed_password  # type:ignore[attr-defined]
            self.tornado_settings["token"] = self.identity_provider.token

        if self._token_set:
            self.log.warning(
                "ServerApp.token config is deprecated in jupyter-server 2.0. Use IdentityProvider.token"
            )
            if self.identity_provider.token_generated:
                # default behavior: generated default token
                # preserve deprecated ServerApp.token config
                self.identity_provider.token_generated = False
                self.identity_provider.token = self.token
            else:
                # identity_provider didn't generate a default token,
                # that means it has some config that should take higher priority than deprecated ServerApp.token
                self.log.warning("Ignoring deprecated ServerApp.token config")

        self.authorizer = self.authorizer_class(
            parent=self, log=self.log, identity_provider=self.identity_provider
        )

    def init_logging(self) -> None:
        """Initialize logging."""
        # This prevents double log messages because tornado use a root logger that
        # self.log is a child of. The logging module dipatches log messages to a log
        # and all of its ancenstors until propagate is set to False.
        self.log.propagate = False

        for log in app_log, access_log, gen_log:
            # consistent log output name (ServerApp instead of tornado.access, etc.)
            log.name = self.log.name
        # hook up tornado 3's loggers to our app handlers
        logger = logging.getLogger("tornado")
        logger.propagate = True
        logger.parent = self.log
        logger.setLevel(self.log.level)

    def init_event_logger(self) -> None:
        """Initialize the Event Bus."""
        self.event_logger = EventLogger(parent=self)
        # Load the core Jupyter Server event schemas
        # All event schemas must start with Jupyter Server's
        # events URI, `JUPYTER_SERVER_EVENTS_URI`.
        schema_ids = [
            "https://events.jupyter.org/jupyter_server/contents_service/v1",
            "https://events.jupyter.org/jupyter_server/gateway_client/v1",
            "https://events.jupyter.org/jupyter_server/kernel_actions/v1",
        ]
        for schema_id in schema_ids:
            # Get the schema path from the schema ID.
            rel_schema_path = schema_id.replace(JUPYTER_SERVER_EVENTS_URI + "/", "") + ".yaml"
            schema_path = DEFAULT_EVENTS_SCHEMA_PATH / rel_schema_path
            # Use this pathlib object to register the schema
            self.event_logger.register_event_schema(schema_path)

    def init_webapp(self) -> None:
        """initialize tornado webapp"""
        self.tornado_settings["allow_origin"] = self.allow_origin
        self.tornado_settings["websocket_compression_options"] = self.websocket_compression_options
        if self.allow_origin_pat:
            self.tornado_settings["allow_origin_pat"] = re.compile(self.allow_origin_pat)
        self.tornado_settings["allow_credentials"] = self.allow_credentials
        self.tornado_settings["autoreload"] = self.autoreload

        # deprecate accessing these directly, in favor of identity_provider?
        self.tornado_settings["cookie_options"] = self.identity_provider.cookie_options
        self.tornado_settings["get_secure_cookie_kwargs"] = (
            self.identity_provider.get_secure_cookie_kwargs
        )
        self.tornado_settings["token"] = self.identity_provider.token

        if self.static_immutable_cache:
            self.tornado_settings["static_immutable_cache"] = self.static_immutable_cache

        # ensure default_url starts with base_url
        if not self.default_url.startswith(self.base_url):
            self.default_url = url_path_join(self.base_url, self.default_url)

        # Socket options validation.
        if self.sock:
            if self.port != DEFAULT_JUPYTER_SERVER_PORT:
                self.log.critical(
                    ("Options --port and --sock are mutually exclusive. Aborting."),
                )
                sys.exit(1)
            else:
                # Reset the default port if we're using a UNIX socket.
                self.port = 0

            if self.open_browser:
                # If we're bound to a UNIX socket, we can't reliably connect from a browser.
                self.log.info(
                    ("Ignoring --ServerApp.open_browser due to --sock being used."),
                )

            if self.file_to_run:
                self.log.critical(
                    ("Options --ServerApp.file_to_run and --sock are mutually exclusive."),
                )
                sys.exit(1)

            if sys.platform.startswith("win"):
                self.log.critical(
                    (
                        "Option --sock is not supported on Windows, but got value of %s. Aborting."
                        % self.sock
                    ),
                )
                sys.exit(1)

        self.web_app = ServerWebApplication(
            self,
            self.default_services,
            self.kernel_manager,
            self.contents_manager,
            self.session_manager,
            self.kernel_spec_manager,
            self.config_manager,
            self.event_logger,
            self.extra_services,
            self.log,
            self.base_url,
            self.default_url,
            self.tornado_settings,
            self.jinja_environment_options,
            authorizer=self.authorizer,
            identity_provider=self.identity_provider,
            kernel_websocket_connection_class=self.kernel_websocket_connection_class,
            websocket_ping_interval=self.websocket_ping_interval,
            websocket_ping_timeout=self.websocket_ping_timeout,
        )
        if self.certfile:
            self.ssl_options["certfile"] = self.certfile
        if self.keyfile:
            self.ssl_options["keyfile"] = self.keyfile
        if self.client_ca:
            self.ssl_options["ca_certs"] = self.client_ca
        if not self.ssl_options:
            # could be an empty dict or None
            # None indicates no SSL config
            self.ssl_options = None  # type:ignore[assignment]
        else:
            # SSL may be missing, so only import it if it's to be used
            import ssl

            # PROTOCOL_TLS selects the highest ssl/tls protocol version that both the client and
            # server support. When PROTOCOL_TLS is not available use PROTOCOL_SSLv23.
            self.ssl_options.setdefault(
                "ssl_version", getattr(ssl, "PROTOCOL_TLS", ssl.PROTOCOL_SSLv23)
            )
            if self.ssl_options.get("ca_certs", False):
                self.ssl_options.setdefault("cert_reqs", ssl.CERT_REQUIRED)

        self.identity_provider.validate_security(self, ssl_options=self.ssl_options)

        if isinstance(self.identity_provider, LegacyIdentityProvider):
            # LegacyIdentityProvider needs access to the tornado settings dict
            self.identity_provider.settings = self.web_app.settings

    def init_resources(self) -> None:
        """initialize system resources"""
        if resource is None:
            self.log.debug(  # type:ignore[unreachable]
                "Ignoring min_open_files_limit because the limit cannot be adjusted (for example, on Windows)"
            )
            return

        old_soft, old_hard = resource.getrlimit(resource.RLIMIT_NOFILE)
        soft = self.min_open_files_limit
        hard = old_hard
        if soft is not None and old_soft < soft:
            if hard < soft:
                hard = soft
            self.log.debug(
                f"Raising open file limit: soft {old_soft}->{soft}; hard {old_hard}->{hard}"
            )
            resource.setrlimit(resource.RLIMIT_NOFILE, (soft, hard))

    def _get_urlparts(
        self, path: t.Optional[str] = None, include_token: bool = False
    ) -> urllib.parse.ParseResult:
        """Constructs a urllib named tuple, ParseResult,
        with default values set by server config.
        The returned tuple can be manipulated using the `_replace` method.
        """
        if self.sock:
            scheme = "http+unix"
            netloc = urlencode_unix_socket_path(self.sock)
        else:
            if not self.ip:
                ip = "localhost"
            # Handle nonexplicit hostname.
            elif self.ip in ("0.0.0.0", "::"):  # noqa: S104
                ip = "%s" % socket.gethostname()
            else:
                ip = f"[{self.ip}]" if ":" in self.ip else self.ip
            netloc = f"{ip}:{self.port}"
            scheme = "https" if self.certfile else "http"
        if not path:
            path = self.default_url
        query = None
        # Don't log full token if it came from config
        if include_token and self.identity_provider.token:
            token = (
                self.identity_provider.token if self.identity_provider.token_generated else "..."
            )
            query = urllib.parse.urlencode({"token": token})
        # Build the URL Parts to dump.
        urlparts = urllib.parse.ParseResult(
            scheme=scheme, netloc=netloc, path=path, query=query or "", params="", fragment=""
        )
        return urlparts

    @property
    def public_url(self) -> str:
        parts = self._get_urlparts(include_token=True)
        # Update with custom pieces.
        if self.custom_display_url:
            # Parse custom display_url
            custom = urllib.parse.urlparse(self.custom_display_url)._asdict()
            # Get pieces that are matter (non None)
            custom_updates = {key: item for key, item in custom.items() if item}
            # Update public URL parts with custom pieces.
            parts = parts._replace(**custom_updates)
        return parts.geturl()

    @property
    def local_url(self) -> str:
        parts = self._get_urlparts(include_token=True)
        # Update with custom pieces.
        if not self.sock:
            parts = parts._replace(netloc=f"127.0.0.1:{self.port}")
        return parts.geturl()

    @property
    def display_url(self) -> str:
        """Human readable string with URLs for interacting
        with the running Jupyter Server
        """
        url = self.public_url + "\n    " + self.local_url
        return url

    @property
    def connection_url(self) -> str:
        urlparts = self._get_urlparts(path=self.base_url)
        return urlparts.geturl()

    def init_signal(self) -> None:
        """Initialize signal handlers."""
        if (
            not sys.platform.startswith("win")
            and sys.stdin  # type:ignore[truthy-bool]
            and sys.stdin.isatty()
        ):
            signal.signal(signal.SIGINT, self._handle_sigint)
        signal.signal(signal.SIGTERM, self._signal_stop)
        if hasattr(signal, "SIGUSR1"):
            # Windows doesn't support SIGUSR1
            signal.signal(signal.SIGUSR1, self._signal_info)
        if hasattr(signal, "SIGINFO"):
            # only on BSD-based systems
            signal.signal(signal.SIGINFO, self._signal_info)

    def _handle_sigint(self, sig: t.Any, frame: t.Any) -> None:
        """SIGINT handler spawns confirmation dialog"""
        # register more forceful signal handler for ^C^C case
        signal.signal(signal.SIGINT, self._signal_stop)
        # request confirmation dialog in bg thread, to avoid
        # blocking the App
        thread = threading.Thread(target=self._confirm_exit)
        thread.daemon = True
        thread.start()

    def _restore_sigint_handler(self) -> None:
        """callback for restoring original SIGINT handler"""
        signal.signal(signal.SIGINT, self._handle_sigint)

    def _confirm_exit(self) -> None:
        """confirm shutdown on ^C

        A second ^C, or answering 'y' within 5s will cause shutdown,
        otherwise original SIGINT handler will be restored.

        This doesn't work on Windows.
        """
        info = self.log.info
        info(_i18n("interrupted"))
        # Check if answer_yes is set
        if self.answer_yes:
            self.log.critical(_i18n("Shutting down..."))
            # schedule stop on the main thread,
            # since this might be called from a signal handler
            self.stop(from_signal=True)
            return
        info(self.running_server_info())
        yes = _i18n("y")
        no = _i18n("n")
        sys.stdout.write(_i18n("Shut down this Jupyter server (%s/[%s])? ") % (yes, no))
        sys.stdout.flush()
        r, w, x = select.select([sys.stdin], [], [], 5)
        if r:
            line = sys.stdin.readline()
            if line.lower().startswith(yes) and no not in line.lower():
                self.log.critical(_i18n("Shutdown confirmed"))
                # schedule stop on the main thread,
                # since this might be called from a signal handler
                self.stop(from_signal=True)
                return
        else:
            if self._stopping:
                # don't show 'no answer' if we're actually stopping,
                # e.g. ctrl-C ctrl-C
                return
            info(_i18n("No answer for 5s:"))
        info(_i18n("resuming operation..."))
        # no answer, or answer is no:
        # set it back to original SIGINT handler
        # use IOLoop.add_callback because signal.signal must be called
        # from main thread
        self.io_loop.add_callback_from_signal(self._restore_sigint_handler)

    def _signal_stop(self, sig: t.Any, frame: t.Any) -> None:
        """Handle a stop signal."""
        self.log.critical(_i18n("received signal %s, stopping"), sig)
        self.stop(from_signal=True)

    def _signal_info(self, sig: t.Any, frame: t.Any) -> None:
        """Handle an info signal."""
        self.log.info(self.running_server_info())

    def init_components(self) -> None:
        """Check the components submodule, and warn if it's unclean"""
        # TODO: this should still check, but now we use bower, not git submodule

    def find_server_extensions(self) -> None:
        """
        Searches Jupyter paths for jpserver_extensions.
        """

        # Walk through all config files looking for jpserver_extensions.
        #
        # Each extension will likely have a JSON config file enabling itself in
        # the "jupyter_server_config.d" directory. Find each of these and
        # merge there results in order of precedence.
        #
        # Load server extensions with ConfigManager.
        # This enables merging on keys, which we want for extension enabling.
        # Regular config loading only merges at the class level,
        # so each level clobbers the previous.
        manager = ExtensionConfigManager(read_config_path=self.config_file_paths)
        extensions = manager.get_jpserver_extensions()

        for modulename, enabled in sorted(extensions.items()):
            if modulename not in self.jpserver_extensions:
                self.config.ServerApp.jpserver_extensions.update({modulename: enabled})
                self.jpserver_extensions.update({modulename: enabled})

    def init_server_extensions(self) -> None:
        """
        If an extension's metadata includes an 'app' key,
        the value must be a subclass of ExtensionApp. An instance
        of the class will be created at this step. The config for
        this instance will inherit the ServerApp's config object
        and load its own config.
        """
        # Create an instance of the ExtensionManager.
        self.extension_manager = ExtensionManager(log=self.log, serverapp=self)
        self.extension_manager.from_jpserver_extensions(self.jpserver_extensions)
        self.extension_manager.link_all_extensions()

    def load_server_extensions(self) -> None:
        """Load any extensions specified by config.

        Import the module, then call the load_jupyter_server_extension function,
        if one exists.

        The extension API is experimental, and may change in future releases.
        """
        self.extension_manager.load_all_extensions()

    def init_mime_overrides(self) -> None:
        # On some Windows machines, an application has registered incorrect
        # mimetypes in the registry.
        # Tornado uses this when serving .css and .js files, causing browsers to
        # reject these files. We know the mimetype always needs to be text/css for css
        # and application/javascript for JS, so we override it here
        # and explicitly tell the mimetypes to not trust the Windows registry
        if os.name == "nt":
            # do not trust windows registry, which regularly has bad info
            mimetypes.init(files=[])
        # ensure css, js are correct, which are required for pages to function
        mimetypes.add_type("text/css", ".css")
        mimetypes.add_type("application/javascript", ".js")
        # for python <3.8
        mimetypes.add_type("application/wasm", ".wasm")

    def shutdown_no_activity(self) -> None:
        """Shutdown server on timeout when there are no kernels or terminals."""
        km = self.kernel_manager
        if len(km) != 0:
            return  # Kernels still running

        if self.extension_manager.any_activity():
            return

        seconds_since_active = (utcnow() - self.web_app.last_activity()).total_seconds()
        self.log.debug("No activity for %d seconds.", seconds_since_active)
        if seconds_since_active > self.shutdown_no_activity_timeout:
            self.log.info(
                "No kernels for %d seconds; shutting down.",
                seconds_since_active,
            )
            self.stop()

    def init_shutdown_no_activity(self) -> None:
        """Initialize a shutdown on no activity."""
        if self.shutdown_no_activity_timeout > 0:
            self.log.info(
                "Will shut down after %d seconds with no kernels.",
                self.shutdown_no_activity_timeout,
            )
            pc = ioloop.PeriodicCallback(self.shutdown_no_activity, 60000)
            pc.start()

    @property
    def http_server(self) -> httpserver.HTTPServer:
        """An instance of Tornado's HTTPServer class for the Server Web Application."""
        try:
            return self._http_server
        except AttributeError:
            msg = (
                "An HTTPServer instance has not been created for the "
                "Server Web Application. To create an HTTPServer for this "
                "application, call `.init_httpserver()`."
            )
            raise AttributeError(msg) from None

    def init_httpserver(self) -> None:
        """Creates an instance of a Tornado HTTPServer for the Server Web Application
        and sets the http_server attribute.
        """
        # Check that a web_app has been initialized before starting a server.
        if not hasattr(self, "web_app"):
            msg = (
                "A tornado web application has not be initialized. "
                "Try calling `.init_webapp()` first."
            )
            raise AttributeError(msg)

        # Create an instance of the server.
        self._http_server = httpserver.HTTPServer(
            self.web_app,
            ssl_options=self.ssl_options,
            xheaders=self.trust_xheaders,
            max_body_size=self.max_body_size,
            max_buffer_size=self.max_buffer_size,
        )

        # binding sockets must be called from inside an event loop
        if not self.sock:
            self._find_http_port()
        self.io_loop.add_callback(self._bind_http_server)

    def _bind_http_server(self) -> None:
        """Bind our http server."""
        success = self._bind_http_server_unix() if self.sock else self._bind_http_server_tcp()
        if not success:
            self.log.critical(
                _i18n(
                    "ERROR: the Jupyter server could not be started because "
                    "no available port could be found."
                )
            )
            self.exit(1)

    def _bind_http_server_unix(self) -> bool:
        """Bind an http server on unix."""
        if unix_socket_in_use(self.sock):
            self.log.warning(_i18n("The socket %s is already in use.") % self.sock)
            return False

        try:
            sock = bind_unix_socket(self.sock, mode=int(self.sock_mode.encode(), 8))
            self.http_server.add_socket(sock)
        except OSError as e:
            if e.errno == errno.EADDRINUSE:
                self.log.warning(_i18n("The socket %s is already in use.") % self.sock)
                return False
            elif e.errno in (errno.EACCES, getattr(errno, "WSAEACCES", errno.EACCES)):
                self.log.warning(_i18n("Permission to listen on sock %s denied") % self.sock)
                return False
            else:
                raise
        else:
            return True

    def _bind_http_server_tcp(self) -> bool:
        """Bind a tcp server."""
        self.http_server.listen(self.port, self.ip)
        return True

    def _find_http_port(self) -> None:
        """Find an available http port."""
        success = False
        port = self.port
        for port in random_ports(self.port, self.port_retries + 1):
            try:
                sockets = bind_sockets(port, self.ip)
                sockets[0].close()
            except OSError as e:
                if e.errno == errno.EADDRINUSE:
                    if self.port_retries:
                        self.log.info(
                            _i18n("The port %i is already in use, trying another port.") % port
                        )
                    else:
                        self.log.info(_i18n("The port %i is already in use.") % port)
                    continue
                if e.errno in (
                    errno.EACCES,
                    getattr(errno, "WSAEACCES", errno.EACCES),
                ):
                    self.log.warning(_i18n("Permission to listen on port %i denied.") % port)
                    continue
                raise
            else:
                success = True
                self.port = port
                break
        if not success:
            if self.port_retries:
                self.log.critical(
                    _i18n(
                        "ERROR: the Jupyter server could not be started because "
                        "no available port could be found."
                    )
                )
            else:
                self.log.critical(
                    _i18n(
                        "ERROR: the Jupyter server could not be started because "
                        "port %i is not available."
                    )
                    % port
                )
            self.exit(1)

    @staticmethod
    def _init_asyncio_patch() -> None:
        """set default asyncio policy to be compatible with tornado

        Tornado 6.0 is not compatible with default asyncio
        ProactorEventLoop, which lacks basic *_reader methods.
        Tornado 6.1 adds a workaround to add these methods in a thread,
        but SelectorEventLoop should still be preferred
        to avoid the extra thread for ~all of our events,
        at least until asyncio adds *_reader methods
        to proactor.
        """
        if sys.platform.startswith("win") and sys.version_info >= (3, 8):
            import asyncio

            try:
                from asyncio import WindowsProactorEventLoopPolicy, WindowsSelectorEventLoopPolicy
            except ImportError:
                pass
                # not affected
            else:
                if type(asyncio.get_event_loop_policy()) is WindowsProactorEventLoopPolicy:
                    # prefer Selector to Proactor for tornado + pyzmq
                    asyncio.set_event_loop_policy(WindowsSelectorEventLoopPolicy())

    @catch_config_error
    def initialize(
        self,
        argv: t.Optional[list[str]] = None,
        find_extensions: bool = True,
        new_httpserver: bool = True,
        starter_extension: t.Any = None,
    ) -> None:
        """Initialize the Server application class, configurables, web application, and http server.

        Parameters
        ----------
        argv : list or None
            CLI arguments to parse.
        find_extensions : bool
            If True, find and load extensions listed in Jupyter config paths. If False,
            only load extensions that are passed to ServerApp directly through
            the `argv`, `config`, or `jpserver_extensions` arguments.
        new_httpserver : bool
            If True, a tornado HTTPServer instance will be created and configured for the Server Web
            Application. This will set the http_server attribute of this class.
        starter_extension : str
            If given, it references the name of an extension point that started the Server.
            We will try to load configuration from extension point
        """
        self._init_asyncio_patch()
        # Parse command line, load ServerApp config files,
        # and update ServerApp config.
        super().initialize(argv=argv)
        if self._dispatching:
            return
        # initialize io loop as early as possible,
        # so configurables, extensions may reference the event loop
        self.init_ioloop()

        # Then, use extensions' config loading mechanism to
        # update config. ServerApp config takes precedence.
        if find_extensions:
            self.find_server_extensions()
        self.init_logging()
        self.init_event_logger()
        self.init_server_extensions()

        # Special case the starter extension and load
        # any server configuration is provides.
        if starter_extension:
            # Configure ServerApp based on named extension.
            point = self.extension_manager.extension_points[starter_extension]
            # Set starter_app property.
            if point.app:
                self._starter_app = point.app
            # Load any configuration that comes from the Extension point.
            self.update_config(Config(point.config))

        # Initialize other pieces of the server.
        self.init_resources()
        self.init_configurables()
        self.init_components()
        self.init_webapp()
        self.init_signal()
        self.load_server_extensions()
        self.init_mime_overrides()
        self.init_shutdown_no_activity()
        if new_httpserver:
            self.init_httpserver()

    async def cleanup_kernels(self) -> None:
        """Shutdown all kernels.

        The kernels will shutdown themselves when this process no longer exists,
        but explicit shutdown allows the KernelManagers to cleanup the connection files.
        """
        if not getattr(self, "kernel_manager", None):
            return
        n_kernels = len(self.kernel_manager.list_kernel_ids())
        kernel_msg = trans.ngettext(
            "Shutting down %d kernel", "Shutting down %d kernels", n_kernels
        )
        self.log.info(kernel_msg % n_kernels)
        await ensure_async(self.kernel_manager.shutdown_all())

    async def cleanup_extensions(self) -> None:
        """Call shutdown hooks in all extensions."""
        if not getattr(self, "extension_manager", None):
            return
        n_extensions = len(self.extension_manager.extension_apps)
        extension_msg = trans.ngettext(
            "Shutting down %d extension", "Shutting down %d extensions", n_extensions
        )
        self.log.info(extension_msg % n_extensions)
        await ensure_async(self.extension_manager.stop_all_extensions())

    def running_server_info(self, kernel_count: bool = True) -> str:
        """Return the current working directory and the server url information"""
        info = t.cast(str, self.contents_manager.info_string()) + "\n"
        if kernel_count:
            n_kernels = len(self.kernel_manager.list_kernel_ids())
            kernel_msg = trans.ngettext("%d active kernel", "%d active kernels", n_kernels)
            info += kernel_msg % n_kernels
            info += "\n"
        # Format the info so that the URL fits on a single line in 80 char display
        info += _i18n(f"Jupyter Server {ServerApp.version} is running at:\n{self.display_url}")
        if self.gateway_config.gateway_enabled:
            info += (
                _i18n("\nKernels will be managed by the Gateway server running at:\n%s")
                % self.gateway_config.url
            )
        return info

    def server_info(self) -> dict[str, t.Any]:
        """Return a JSONable dict of information about this server."""
        return {
            "url": self.connection_url,
            "hostname": self.ip if self.ip else "localhost",
            "port": self.port,
            "sock": self.sock,
            "secure": bool(self.certfile),
            "base_url": self.base_url,
            "token": self.identity_provider.token,
            "root_dir": os.path.abspath(self.root_dir),
            "password": bool(self.password),
            "pid": os.getpid(),
            "version": ServerApp.version,
        }

    def write_server_info_file(self) -> None:
        """Write the result of server_info() to the JSON file info_file."""
        try:
            with secure_write(self.info_file) as f:
                json.dump(self.server_info(), f, indent=2, sort_keys=True)
        except OSError as e:
            self.log.error(_i18n("Failed to write server-info to %s: %r"), self.info_file, e)

    def remove_server_info_file(self) -> None:
        """Remove the jpserver-<pid>.json file created for this server.

        Ignores the error raised when the file has already been removed.
        """
        try:
            os.unlink(self.info_file)
        except OSError as e:
            if e.errno != errno.ENOENT:
                raise

    def _resolve_file_to_run_and_root_dir(self) -> str:
        """Returns a relative path from file_to_run
        to root_dir. If root_dir and file_to_run
        are incompatible, i.e. on different subtrees,
        crash the app and log a critical message. Note
        that if root_dir is not configured and file_to_run
        is configured, root_dir will be set to the parent
        directory of file_to_run.
        """
        rootdir_abspath = pathlib.Path(self.root_dir).absolute()
        file_rawpath = pathlib.Path(self.file_to_run)
        combined_path = (rootdir_abspath / file_rawpath).absolute()
        is_child = str(combined_path).startswith(str(rootdir_abspath))

        if is_child:
            if combined_path.parent != rootdir_abspath:
                self.log.debug(
                    "The `root_dir` trait is set to a directory that's not "
                    "the immediate parent directory of `file_to_run`. Note that "
                    "the server will start at `root_dir` and open the "
                    "the file from the relative path to the `root_dir`."
                )
            return str(combined_path.relative_to(rootdir_abspath))

        self.log.critical(
            "`root_dir` and `file_to_run` are incompatible. They "
            "don't share the same subtrees. Make sure `file_to_run` "
            "is on the same path as `root_dir`."
        )
        self.exit(1)
        return ""

    def _write_browser_open_file(self, url: str, fh: t.Any) -> None:
        """Write the browser open file."""
        if self.identity_provider.token:
            url = url_concat(url, {"token": self.identity_provider.token})
        url = url_path_join(self.connection_url, url)

        jinja2_env = self.web_app.settings["jinja2_env"]
        template = jinja2_env.get_template("browser-open.html")
        fh.write(template.render(open_url=url, base_url=self.base_url))

    def write_browser_open_files(self) -> None:
        """Write an `browser_open_file` and `browser_open_file_to_run` files

        This can be used to open a file directly in a browser.
        """
        # default_url contains base_url, but so does connection_url
        self.write_browser_open_file()

        # Create a second browser open file if
        # file_to_run is set.
        if self.file_to_run:
            # Make sure file_to_run and root_dir are compatible.
            file_to_run_relpath = self._resolve_file_to_run_and_root_dir()

            file_open_url = url_escape(
                url_path_join(self.file_url_prefix, *file_to_run_relpath.split(os.sep))
            )

            with open(self.browser_open_file_to_run, "w", encoding="utf-8") as f:
                self._write_browser_open_file(file_open_url, f)

    def write_browser_open_file(self) -> None:
        """Write an jpserver-<pid>-open.html file

        This can be used to open the notebook in a browser
        """
        # default_url contains base_url, but so does connection_url
        open_url = self.default_url[len(self.base_url) :]

        with open(self.browser_open_file, "w", encoding="utf-8") as f:
            self._write_browser_open_file(open_url, f)

    def remove_browser_open_files(self) -> None:
        """Remove the `browser_open_file` and `browser_open_file_to_run` files
        created for this server.

        Ignores the error raised when the file has already been removed.
        """
        self.remove_browser_open_file()
        try:
            os.unlink(self.browser_open_file_to_run)
        except OSError as e:
            if e.errno != errno.ENOENT:
                raise

    def remove_browser_open_file(self) -> None:
        """Remove the jpserver-<pid>-open.html file created for this server.

        Ignores the error raised when the file has already been removed.
        """
        try:
            os.unlink(self.browser_open_file)
        except OSError as e:
            if e.errno != errno.ENOENT:
                raise

    def _prepare_browser_open(self) -> tuple[str, t.Optional[str]]:
        """Prepare to open the browser."""
        if not self.use_redirect_file:
            uri = self.default_url[len(self.base_url) :]

            if self.identity_provider.token:
                uri = url_concat(uri, {"token": self.identity_provider.token})

        if self.file_to_run:  # noqa: SIM108
            # Create a separate, temporary open-browser-file
            # pointing at a specific file.
            open_file = self.browser_open_file_to_run
        else:
            # otherwise, just return the usual open browser file.
            open_file = self.browser_open_file

        if self.use_redirect_file:
            assembled_url = urljoin("file:", pathname2url(open_file))
        else:
            assembled_url = url_path_join(self.connection_url, uri)

        return assembled_url, open_file

    def launch_browser(self) -> None:
        """Launch the browser."""
        # Deferred import for environments that do not have
        # the webbrowser module.
        import webbrowser

        try:
            browser = webbrowser.get(self.browser or None)
        except webbrowser.Error as e:
            self.log.warning(_i18n("No web browser found: %r.") % e)
            browser = None

        if not browser:
            return

        assembled_url, _ = self._prepare_browser_open()

        def target():
            assert browser is not None
            browser.open(assembled_url, new=self.webbrowser_open_new)

        threading.Thread(target=target).start()

    def start_app(self) -> None:
        """Start the Jupyter Server application."""
        super().start()

        if not self.allow_root:
            # check if we are running as root, and abort if it's not allowed
            try:
                uid = os.geteuid()
            except AttributeError:
                uid = -1  # anything nonzero here, since we can't check UID assume non-root
            if uid == 0:
                self.log.critical(
                    _i18n("Running as root is not recommended. Use --allow-root to bypass.")
                )
                self.exit(1)

        info = self.log.info
        for line in self.running_server_info(kernel_count=False).split("\n"):
            info(line)
        info(
            _i18n(
                "Use Control-C to stop this server and shut down all kernels (twice to skip confirmation)."
            )
        )
        if "dev" in __version__:
            info(
                _i18n(
                    "Welcome to Project Jupyter! Explore the various tools available"
                    " and their corresponding documentation. If you are interested"
                    " in contributing to the platform, please visit the community"
                    " resources section at https://jupyter.org/community.html."
                )
            )

        self.write_server_info_file()

        if not self.no_browser_open_file:
            self.write_browser_open_files()

        # Handle the browser opening.
        if self.open_browser and not self.sock:
            self.launch_browser()

        if self.identity_provider.token and self.identity_provider.token_generated:
            # log full URL with generated token, so there's a copy/pasteable link
            # with auth info.
            if self.sock:
                self.log.critical(
                    "\n".join(
                        [
                            "\n",
                            "Jupyter Server is listening on %s" % self.display_url,
                            "",
                            (
                                "UNIX sockets are not browser-connectable, but you can tunnel to "
                                f"the instance via e.g.`ssh -L 8888:{self.sock} -N user@this_host` and then "
                                f"open e.g. {self.connection_url} in a browser."
                            ),
                        ]
                    )
                )
            else:
                if self.no_browser_open_file:
                    message = [
                        "\n",
                        _i18n("To access the server, copy and paste one of these URLs:"),
                        "    %s" % self.display_url,
                    ]
                else:
                    message = [
                        "\n",
                        _i18n(
                            "To access the server, open this file in a browser:",
                        ),
                        "    %s" % urljoin("file:", pathname2url(self.browser_open_file)),
                        _i18n(
                            "Or copy and paste one of these URLs:",
                        ),
                        "    %s" % self.display_url,
                    ]

                self.log.critical("\n".join(message))

    async def _cleanup(self) -> None:
        """General cleanup of files, extensions and kernels created
        by this instance ServerApp.
        """
        self.remove_server_info_file()
        self.remove_browser_open_files()
        await self.cleanup_extensions()
        await self.cleanup_kernels()
        try:
            await self.kernel_websocket_connection_class.close_all()  # type:ignore[attr-defined]
        except AttributeError:
            # This can happen in two different scenarios:
            #
            # 1. During tests, where the _cleanup method is invoked without
            #    the corresponding initialize method having been invoked.
            # 2. If the provided `kernel_websocket_connection_class` does not
            #    implement the `close_all` class method.
            #
            # In either case, we don't need to do anything and just want to treat
            # the raised error as a no-op.
            pass
        if getattr(self, "kernel_manager", None):
            self.kernel_manager.__del__()
        if getattr(self, "session_manager", None):
            self.session_manager.close()
        if hasattr(self, "http_server"):
            # Stop a server if its set.
            self.http_server.stop()

    def start_ioloop(self) -> None:
        """Start the IO Loop."""
        if sys.platform.startswith("win"):
            # add no-op to wake every 5s
            # to handle signals that may be ignored by the inner loop
            pc = ioloop.PeriodicCallback(lambda: None, 5000)
            pc.start()
        try:
            self.io_loop.start()
        except KeyboardInterrupt:
            self.log.info(_i18n("Interrupted..."))

    def init_ioloop(self) -> None:
        """init self.io_loop so that an extension can use it by io_loop.call_later() to create background tasks"""
        self.io_loop = ioloop.IOLoop.current()

    def start(self) -> None:
        """Start the Jupyter server app, after initialization

        This method takes no arguments so all configuration and initialization
        must be done prior to calling this method."""
        self.start_app()
        self.start_ioloop()

    async def _stop(self) -> None:
        """Cleanup resources and stop the IO Loop."""
        await self._cleanup()
        if getattr(self, "io_loop", None):
            self.io_loop.stop()

    def stop(self, from_signal: bool = False) -> None:
        """Cleanup resources and stop the server."""
        # signal that stopping has begun
        self._stopping = True
        if hasattr(self, "http_server"):
            # Stop a server if its set.
            self.http_server.stop()
        if getattr(self, "io_loop", None):
            # use IOLoop.add_callback because signal.signal must be called
            # from main thread
            if from_signal:
                self.io_loop.add_callback_from_signal(self._stop)
            else:
                self.io_loop.add_callback(self._stop)


def list_running_servers(
    runtime_dir: t.Optional[str] = None, log: t.Optional[logging.Logger] = None
) -> t.Generator[t.Any, None, None]:
    """Iterate over the server info files of running Jupyter servers.

    Given a runtime directory, find jpserver-* files in the security directory,
    and yield dicts of their information, each one pertaining to
    a currently running Jupyter server instance.
    """
    if runtime_dir is None:
        runtime_dir = jupyter_runtime_dir()

    # The runtime dir might not exist
    if not os.path.isdir(runtime_dir):
        return

    for file_name in os.listdir(runtime_dir):
        if re.match("jpserver-(.+).json", file_name):
            with open(os.path.join(runtime_dir, file_name), encoding="utf-8") as f:
                # Handle race condition where file is being written.
                try:
                    info = json.load(f)
                except json.JSONDecodeError:
                    continue

            # Simple check whether that process is really still running
            # Also remove leftover files from IPython 2.x without a pid field
            if ("pid" in info) and check_pid(info["pid"]):
                yield info
            else:
                # If the process has died, try to delete its info file
                try:
                    os.unlink(os.path.join(runtime_dir, file_name))
                except OSError as e:
                    if log:
                        log.warning(_i18n("Deleting server info file failed: %s.") % e)


# -----------------------------------------------------------------------------
# Main entry point
# -----------------------------------------------------------------------------

main = launch_new_instance = ServerApp.launch_instance