Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

file 3833 lines (3428 sloc) 246.699 kb
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 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />

        <title>The Node Beginner Book » A comprehensive Node.js tutorial</title>
        <meta name="description" content="A comprehensive Node.js tutorial for beginners: Learn how to build a full blown web application with server-side JavaScript" />
        
        <link rel="icon" href="favicon.png" type="image/png" />
        <link rel="stylesheet" type="text/css" href="default.css" />
    </head>
    <body>
        <div id="forkmeongithub">
            <a href="https://github.com/ManuelKiessling/NodeBeginnerBook"><img src="fork_me_on_github.png" width="149" height="149" alt="Fork me on GitHub" /></a>
        </div>

        <div id="ibookstore-banner">
            <a href="buy-ibook/index.html"><img src="ibookstore-banner.jpg" width="100%" /></a>
        </div>

        <div id="translations">
            <table>
                <tr>
                    <td>
                        <a href="index-jp.html">
                            <div class="flag"><img src="jp-flag.png" width="24" height="24" alt="japanese flag" /></div>
                            <div class="text">日本語で読む</div>
                        </a>
                    </td>
                    <td>
                        <a href="index-es.html">
                            <div class="flag"><img src="es-flag.png" width="24" height="24" alt="spanish flag" /></div>
                            <div class="text">Lee este tutorial en Español</div>
                        </a>
                    </td>
                    <td>
                        <a href="index-kr.html">
                            <div class="flag"><img src="kr-flag.png" width="24" height="24" alt="korean flag" /></div>
                            <div class="text">이 튜토리얼을 한글로 보세요</div>
                        </a>
                    </td>
                </tr>
                <tr>
                    <td>
                        <a href="index-zh-cn.html">
                            <div class="flag"><img src="cn-flag.png" width="24" height="24" alt="chinese flag" /></div>
                            <div class="text">阅读本书中文版</div>
                        </a>
                    </td>
                    <td>
                        <a href="index-zh-tw.html">
                            <div class="flag"><img src="cn-flag.png" width="24" height="24" alt="chinese flag" /></div>
                            <div class="text">阅读本书繁体中文版</div>
                        </a>
                    </td>
                    <td>
                        <a href="http://www.nodebeginner.ru">
                            <div class="flag"><img src="ru-flag.png" width="24" height="24" alt="russian flag" /></div>
                            <div class="text">Читать этот учебник на русском</div>
                        </a>
                    </td>
                </tr>
            </table>
        </div>

        <div class="buybox">
            <div class="buy-the-bundle">
                <div class="cover">
                    <p>
                        The perfect introduction plus the perfect reference in one bundle!
                    </p>
                    <a href="buy-bundle/index.html"><img src="the_node_beginner_book_cover_small.png" height="86" width="57" /></a>
                    <a href="buy-bundle/index.html"><img src="hands-on_node.js_cover.png" height="86" width="57" /></a>
                </div>
                <div class="description">
                    <p>
                        LeanBundle currently offers
                        the final version of
                        <br />
                        <strong>The Node Beginner Book</strong>
                        <br />
                        plus Pedro Teixeira's excellent
                        <br />
                        <strong>Hands-on Node.js</strong> for only
                        <br />
                        <br />
                        <strong class="price dollarsign">$</strong><strong class="price">9.99</strong>
                        <br />
                        (regular price <del>$21.98</del>)
                    </p>
                </div>
                <div class="buy">
                    <p>
                        226 pages in total
                        <br />
                        PDF, ePub & MOBI
                        <br />
                        Direct download
                        <br />
                        Free updates
                    </p>
                    <a class="buttonlink" href="buy-bundle/index.html">
                        <div class="button">Buy this<br />bundle now</div>
                    </a>
                </div>
            </div>

            <div class="buy-kindle">
                <div class="inner">
                    <a href="buy-kindle/index.html"><img class="cover" src="the_node_beginner_book_cover_small.png" height="86" width="57" /></a>
                    <br />
                    <a href="buy-kindle/reviews.html"><img class="stars" src="amazon_rating_stars.png" width="65" height="12" /></a>
                    <br />
                    (<a href="buy-kindle/reviews.html">Read customer reviews</a>)
                    <br />
                    <a href="buy-kindle/index.html"><img class="button" src="add_to_kindle_button.png" width="102" height="25"/></a>
                </div>
            </div>
        </div>


        <div id="book">
        <div>
        <h1>The Node Beginner Book</h1>

        <div id="author">A Node.js tutorial by <a href="http://twitter.com/manuelkiessling">Manuel Kiessling</a></div>

        <div id="social">
            <a href="https://twitter.com/share" class="twitter-share-button" data-url="http://www.nodebeginner.org" data-text="The Node Beginner Book » A comprehensive Node.js tutorial:" data-via="manuelkiessling">Tweet</a>
            <br />
            <g:plusone size="medium"></g:plusone>
        </div>

        <a name="about"></a>

        <h2>About</h2>

        <p>
            The aim of this document is to get you started with developing
            applications with Node.js, teaching you everything you need to
            know about "advanced" JavaScript along the way. It goes way
            beyond your typical "Hello World" tutorial.
        </p>

        <a name="status"></a>

        <h3>Status</h3>

        <p>
            You are reading the final version of this book, i.e., updates
            are only done to correct errors or to reflect changes in new
            versions of Node.js. It was last updated on February 12, 2012.
        </p>

        <p>
            The code samples in this book are tested to work with Node.js
            version 0.6.11.
        </p>

        <a name="intended-audience"></a>

        <h3>Intended audience</h3>

        <p>
            This document will probably fit best for readers that have a
            background similar to my own: experienced with at least one
            object-oriented language like Ruby, Python, PHP or Java, only little
            experience with JavaScript, and completely new to Node.js.
        </p>

        <p>
            Aiming at developers that already have experience with other
            programming languages means that this document won't cover
            really basic stuff like data types, variables, control structures
            and the likes. You already need to know about these to understand
            this document.
        </p>

        <p>
            However, because functions and objects in JavaScript are different
            from their counterparts in most other languages, these will be
            explained in more detail.
        </p>

        <a name="structure"></a>

        <h3>Structure of this document</h3>

        <p>
            Upon finishing this document, you will have created a complete web
            application which allows the users of this application to view web
            pages and upload files.
        </p>

        <p>
            Which, of course, is not exactly
            world-changing, but we will go some extra miles and not only create
            the code that is "just enough" to make these use cases possible,
            but create a simple, yet complete framework to cleanly separate the
            different aspects of our application. You will see what I mean in a
            minute.
        </p>

        <p>
            We will start with looking at how JavaScript development in Node.js
            is different from JavaScript development in a browser.
        </p>

        <p>
            Next, we will stay with the good old tradition of writing a "Hello
            World" application, which is a most basic Node.js application that
            "does" something.
        </p>

        <p>
            Then, we will discuss what kind of "real" application we want to
            build, dissect the different parts which need to be implemented to
            assemble this application, and start working on each of these parts
            step-by-step.
        </p>

        <p>
            As promised, along the way we will learn about some of the more
            advanced concepts of JavaScript, how to make use of them, and
            look at why it makes sense to use these concepts instead of
            those we know from other programming languages.
        </p>

        <p>
            The source code of the finished application is available through
            <a href="https://github.com/ManuelKiessling/NodeBeginnerBook/tree/master/code/application">the
                NodeBeginnerBook Github repository</a>.
        </p>

        <div id="table-of-contents-headline">Table of contents</div>
        <div id="table-of-contents">
            <ul>

                <li><a href="#about">About</a>
                    <ul>
                        <li><a href="#status">Status</a></li>
                        <li><a href="#intended-audience">Intended audience</a></li>
                        <li><a href="#structure">Structure of this document</a></li>
                    </ul>
                </li>

                <li><a href="#javascript-and-nodejs">JavaScript and Node.js</a>
                    <ul>
                        <li><a href="#javascript-and-you">JavaScript and You</a></li>
                        <li><a href="#a-word-of-warning">A word of warning</a></li>
                        <li><a href="#server-side-javascript">Server-side JavaScript</a></li>
                        <li><a href="#hello-world">"Hello World"</a></li>

                    </ul>
                </li>
                <li><a href="#a-full-blown-web-application-with-nodejs">A full blown web application with Node.js</a>
                    <ul>
                        <li><a href="#the-use-cases">The use cases</a></li>
                        <li><a href="#the-application-stack">The application stack</a></li>
                    </ul>

                </li>
                <li><a href="#building-the-application-stack">Building the application stack</a>
                    <ul>
                        <li><a href="#a-basic-http-server">A basic HTTP server</a></li>
                        <li><a href="#analyzing-our-http-server">Analyzing our HTTP server</a></li>
                        <li><a href="#passing-functions-around">Passing functions around</a></li>
                        <li><a href="#how-function-passing-makes-our-http-server-work">How function passing makes our
                            HTTP server work</a></li>

                        <li><a href="#event-driven-callbacks">Event-driven asynchronous callbacks</a></li>
                        <li><a href="#how-our-server-handles-requests">How our server handles requests</a></li>
                        <li><a href="#finding-a-place-for-our-server-module">Finding a place for our server module</a>
                        </li>
                        <li><a href="#whats-needed-to-route-requests">What's needed to "route" requests?</a></li>
                        <li><a href="#execution-in-the-kongdom-of-verbs">Execution in the kingdom of verbs</a></li>
                        <li><a href="#routing-to-real-request-handlers">Routing to real request handlers</a></li>

                        <li><a href="#making-the-request-handlers-respond">Making the request handlers respond</a>
                            <ul>
                                <li><a href="#how-to-not-do-it">How to not do it</a></li>
                                <li><a href="#blocking-and-non-blocking">Blocking and non-blocking</a></li>
                                <li><a href="#responding-request-handlers-with-non-blocking-operations">Responding
                                    request handlers with non-blocking operations</a>
                                </li>
                            </ul>

                        </li>
                        <li><a href="#serving-something-useful">Serving something useful</a>
                            <ul>
                                <li><a href="#handling-post-requests">Handling POST requests</a></li>
                                <li><a href="#handling-file-uploads">Handling file uploads</a></li>
                            </ul>
                        </li>

                        <li><a href="#conclusion-and-outlook">Conclusion and outlook</a></li>
                    </ul>
                </li>
            </ul>
        </div>

        <a name="javascript-and-nodejs"></a>

        <h2>JavaScript and Node.js</h2>

        <a name="javascript-and-you"></a>

        <h3>JavaScript and You</h3>

        <p>
            Before we talk about all the technical stuff, let's take a
            moment and talk about you and your relationship with
            JavaScript. This chapter is here to allow you to estimate
            if reading this document any further makes sense for you.
        </p>

        <p>
            If you are like me, you started with HTML "development"
            long ago, by writing HTML documents. You came along this
            funny thing called JavaScript, but you only used it in a
            very basic way, adding interactivity to your web pages
            every now and then.
        </p>

        <p>
            What you really wanted was "the real thing", you wanted to
            know how to build complex web sites - you learned a
            programming language like PHP, Ruby, Java, and started
            writing "backend" code.
        </p>

        <p>
            Nevertheless, you kept an eye on JavaScript, you saw that
            with the introduction of jQuery, Prototype and the likes,
            things got more advanced in JavaScript land, and that this
            language really was about more than <em>window.open()</em>.
        </p>

        <p>
            However, this was all still frontend stuff, and although it
            was nice to have jQuery at your disposal whenever you felt
            like spicing up a web page, at the end of the day you were,
            at best, a JavaScript <em>user</em>, but not a JavaScript
            <em>developer</em>.
        </p>

        <p>
            And then came Node.js. JavaScript on the server, how cool
            is that?
        </p>

        <p>
            You decided that it's about time to check out the old, new
            JavaScript. But wait, writing Node.js applications is the
            one thing; understanding why they need to be written the
            way they are written means - understanding JavaScript.
            And this time for real.
        </p>

        <p>
            Here is the problem: Because JavaScript really lives two,
            maybe even three lives (the funny little DHMTL helper from
            the mid-90's, the more serious frontend stuff like jQuery
            and the likes, and now server-side), it's not that easy to
            find information that helps you to learn JavaScript the
            "right" way, in order to write Node.js applications in a
            fashion that makes you feel you are not just using
            JavaScript, you are actually developing it.
        </p>

        <p>
            Because that's the catch: you already are an experienced
            developer, you don't want to learn a new technique by just
            hacking around and mis-using it; you want to be sure that
            you are approaching it from the right angle.
        </p>

        <p>
            There is, of course, excellent documentation out there.
            But documentation alone sometimes isn't enough. What is
            needed is guidance.
        </p>

        <p>
            My goal is to provide a guide for you.
        </p>

        <a name="a-word-of-warning"></a>

        <h3>A word of warning</h3>

        <p>
            There are some really excellent JavaScript people out
            there. I'm not one of them.
        </p>

        <p>
            I'm really just the guy I talked about in the previous
            paragraph. I know a thing or two about developing backend
            web applications, but I'm still new to "real" JavaScript
            and still new to Node.js. I learned some of the more
            advanced aspects of JavaScript just recently.
            I'm not experienced.
        </p>

        <p>
            Which is why this is no "from novice to expert" book. It's
            more like "from novice to advanced novice".
        </p>

        <p>
            If I don't fail, then this will be the kind of
            document I wish I had when starting with Node.js.
        </p>

        <a name="server-side-javascript"></a>

        <h3>Server-side JavaScript</h3>

        <p>
            The first incarnations of JavaScript lived in browsers.
            But this is just the context. It defines what you can
            do with the language, but it doesn't say much about what
            the language itself can do. JavaScript is a "complete"
            language: you can use it in many contexts and achieve
            everything with it you can achieve with any other
            "complete" language.
        </p>

        <p>
            Node.js really is just another context: it allows you to run
            JavaScript code in the backend, outside a browser.
        </p>

        <p>
            In order to execute the JavaScript you intend to run in the
            backend, it needs to be interpreted and, well, executed.
            This is what Node.js does, by making use of Google's V8 VM, the
            same runtime environment for JavaScript that Google
            Chrome uses.
        </p>

        <p>
            Plus, Node.js ships with a lot of useful modules, so you don't
            have to write everything from scratch, like for example
            something that outputs a string on the console.
        </p>

        <p>
            Thus, Node.js is really two things: a runtime environment and a
            library.
        </p>

        <p>
            In order to make use of these, you need to install Node.js.
            Instead of repeating the process here, I kindly ask you to
            visit
            <a href="https://github.com/joyent/node/wiki/Installation" title="Building and Installing Node.js">the
                official
                installation instructions</a>. Please come back once you
            are up and running.
        </p>

        <a name="hello-world"></a>

        <h3>"Hello World"</h3>

        <p>
            Ok, let's just jump in the cold water and write our first
            Node.js application: "Hello World".
        </p>

        <p>
            Open your favorite editor and create a file called
            <em>helloworld.js</em>. We want it to write "Hello World"
            to STDOUT, and here is the code needed to do that:
        </p>
        <pre class="prettyprint lang-js"><span class="pln">console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span class="str">"Hello World"</span><span class="pun">);</span></pre>
        <p>
            Save the file, and execute it through Node.js:
        </p>

        <pre>node helloworld.js</pre>
        <p>
            This should output <em>Hello World</em> on your terminal.
        </p>

        <p>
            Ok, this stuff is boring, right? Let's write some real
            stuff.
        </p>


        <a name="a-full-blown-web-application-with-nodejs"></a>

        <h2>A full blown web application with Node.js</h2>

        <a name="the-use-cases"></a>

        <h3>The use cases</h3>

        <p>
            Let's keep it simple, but realistic:
        </p>
        <ul>

            <li>
                The user should be able to use our application with
                a web browser
            </li>
            <li>
                The user should see a welcome page when
                requesting http://<em>domain</em>/start which displays a
                file upload form
            </li>
            <li>
                By choosing an image file to upload and submitting the
                form, this image should then be uploaded to
                http://<em>domain</em>/upload, where it is displayed once
                the upload is finished
            </li>

        </ul>
        <p>
            Fair enough. Now, you could achieve this goal by googling
            and hacking together <em>something</em>. But that's not
            what we want to do here.
        </p>

        <p>
            Furthermore, we don't want to write only the most basic
            code to achieve the goal, however elegant and correct this code
            might be. We will intentionally add more abstraction than
            necessary in order to get a feeling for building more
            complex Node.js applications.
        </p>

        <a name="the-application-stack"></a>

        <h3>The application stack</h3>

        <p>
            Let's dissect our application. Which parts need to be
            implemented in order to fulfill the use cases?
        </p>

        <ul>
            <li>
                We want to serve web pages, therefore we need an
                <strong>HTTP server</strong>
            </li>

            <li>
                Our server will need to answer differently to
                requests, depending on which URL the request was
                asking for, thus we need some kind of
                <strong>router</strong> in order to map requests
                to request handlers
            </li>
            <li>
                To fullfill the requests that arrived at the server
                and have been routed using the router, we need
                actual <strong>request handlers</strong>
            </li>
            <li>

                The router probably should also treat any incoming
                POST data and give it to the request handlers in
                a convenient form, thus we need <strong>request
                data handling</strong>
            </li>
            <li>
                We not only want to handle requests for URLs, we
                also want to display content when these URLs are
                requested, which means we need some kind of
                <strong>view logic</strong> the request handlers
                can use in order to send content to the user's
                browser
            </li>
            <li>
                Last but not least, the user will be able to upload
                images, so we are going to need some kind of
                <strong>upload handling</strong> which takes care of
                the details
            </li>
        </ul>

        <p>
            Let's think a moment about how we would build this stack
            with PHP. It's not exactly a secret that the typical setup
            would be an Apache HTTP server with mod_php5 installed.
            <br>
            Which in turn means that the whole "we need to be able to
            serve web pages and receive HTTP requests" stuff doesn't
            happen within PHP itself.
        </p>

        <p>
            Well, with node, things are a bit different. Because with
            Node.js, we not only implement our application, we also
            implement the whole HTTP server. In fact, our web
            application and its web server are basically the same.
        </p>

        <p>
            This might sound like a lot of work, but we will see in a
            moment that with Node.js, it's not.
        </p>

        <p>
            Let's just start at the beginning and implement the first
            part of our stack, the HTTP server.
        </p>

        <a name="building-the-application-stack"></a>

        <h2>Building the application stack</h2>

        <a name="a-basic-http-server"></a>

        <h3>A basic HTTP server</h3>

        <p>
            When I arrived at the point where I wanted to start with my
            first "real" Node.js application, I wondered not only how to
            actually code it, but also how to organize my code.
            <br>
            Do I need to have everything in one file? Most tutorials on
            the web that teach you how to write a basic HTTP server in
            Node.js have all the logic in one place. What if I want to
            make sure that my code stays readable the more stuff I
            implement?
        </p>

        <p>
            Turns out, it's relatively easy to keep the different
            concerns of your code separated, by putting them in
            modules.
        </p>

        <p>
            This allows you to have a clean main file, which you
            execute with Node.js, and clean modules that can be used by
            the main file and among each other.
        </p>

        <p>
            So, let's create a main file which we use to start our
            application, and a module file where our HTTP server code
            lives.
        </p>

        <p>
            My impression is that it's more or less a standard to name
            your main file <em>index.js</em>. It makes sense to put our
            server module into a file named <em>server.js</em>.
        </p>

        <p>
            Let's start with the server module. Create the file
            <em>server.js</em> in the root directory of your project,
            and fill it with the following code:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br>http</span><span
                class="pun">.</span><span class="pln">createServer</span><span class="pun">(</span><span class="kwd">function</span><span
                class="pun">(</span><span class="pln">request</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/plain"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; response</span><span class="pun">.</span><span class="pln">write</span><span
                class="pun">(</span><span class="str">"Hello World"</span><span class="pun">);</span><span
                class="pln"><br>&nbsp; response</span><span class="pun">.</span><span class="pln">end</span><span
                class="pun">();</span><span class="pln"><br></span><span class="pun">}).</span><span
                class="pln">listen</span><span class="pun">(</span><span class="lit">8888</span><span
                class="pun">);</span></pre>

        <p>
            That's it! You just wrote a working HTTP server. Let's
            prove it by running and testing it. First, execute your
            script with Node.js:
        </p>
        <pre>node server.js</pre>
        <p>
            Now, open your browser and point it at
            <a href="http://localhost:8888/" rel="nofollow">http://localhost:8888/</a>.
            This should display a web page that says "Hello World".
        </p>

        <p>
            That's quite interesting, isn't it. How about talking about
            what's going on here and leaving the question of how to
            organize our project for later? I promise we'll get back to
            it.
        </p>

        <a name="analyzing-our-http-server"></a>

        <h3>Analyzing our HTTP server</h3>

        <p>
            Well, then, let's analyze what's actually going on here.
        </p>

        <p>
            The first line <em>require</em>s the <em>http</em> module
            that ships with Node.js and makes it accessible through the
            variable <em>http</em>.
        </p>

        <p>
            We then call one of the functions the http module offers:
            <em>createServer</em>. This function returns an object, and
            this object has a method named <em>listen</em>, and takes
            a numeric value which indicates the port number our HTTP
            server is going to listen on.
        </p>

        <p>
            Please ignore for a second the function definition that
            follows the opening bracket of <em>http.createServer</em>.
        </p>

        <p>
            We could have written the code that starts our server and
            makes it listen at port 8888 like this:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br></span><span class="kwd">var</span><span
                class="pln"> server </span><span class="pun">=</span><span class="pln"> http</span><span
                class="pun">.</span><span class="pln">createServer</span><span class="pun">();</span><span
                class="pln"><br>server</span><span class="pun">.</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span></pre>

        <p>
            That would start an HTTP server listening at port 8888
            and doing nothing else (not even answering any incoming
            requests).
        </p>

        <p>
            The really interesting (and, if your background is a more
            conservative language like PHP, odd looking) part is the
            function definition right there where you would expect the
            first parameter of the <em>createServer()</em> call.
        </p>

        <p>
            Turns out, this function definition IS the first (and only)
            parameter we are giving to the <em>createServer()</em>

            call. Because in JavaScript, functions can be passed around
            like any other value.
        </p>

        <a name="passing-functions-around"></a>

        <h3>Passing functions around</h3>

        <p>
            You can, for example, do something like this:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> say</span><span
                class="pun">(</span><span class="pln">word</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span
                class="pln">word</span><span class="pun">);</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> execute</span><span
                class="pun">(</span><span class="pln">someFunction</span><span class="pun">,</span><span class="pln"> value</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; someFunction</span><span
                class="pun">(</span><span class="pln">value</span><span class="pun">);</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>execute</span><span
                class="pun">(</span><span class="pln">say</span><span class="pun">,</span><span
                class="pln"> </span><span class="str">"Hello"</span><span class="pun">);</span></pre>

        <p>
            Read this carefully! What we are doing here is, we pass the
            function <em>say</em> as the first parameter to the
            <em>execute</em> function. Not the return value of
            <em>say</em>, but <em>say</em> itself!
        </p>

        <p>
            Thus, <em>say</em> becomes the local variable
            <em>someFunction</em> within <em>execute</em>, and execute
            can call the function in this variable by issuing
            <em>someFunction()</em> (adding brackets).
        </p>

        <p>
            Of course, because <em>say</em> takes one parameter,
            <em>execute</em> can pass such a parameter when calling
            <em>someFunction</em>.
        </p>

        <p>
            We can, as we just did, pass a function as a parameter to
            another function by its name. But we don't have to take this
            indirection of first defining, then passing it - we can
            define and pass a function as a parameter to another
            function in-place:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> execute</span><span
                class="pun">(</span><span class="pln">someFunction</span><span class="pun">,</span><span class="pln"> value</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; someFunction</span><span
                class="pun">(</span><span class="pln">value</span><span class="pun">);</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>execute</span><span
                class="pun">(</span><span class="kwd">function</span><span class="pun">(</span><span
                class="pln">word</span><span class="pun">){</span><span class="pln"> console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span
                class="pln">word</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">},</span><span class="pln"> </span><span class="str">"Hello"</span><span
                class="pun">);</span></pre>

        <p>
            We define the function we want to pass to <em>execute</em>
            right there at the place where <em>execute</em> expects its
            first parameter.
        </p>

        <p>
            This way, we don't even need to give the function a name,
            which is why this is called an <em>anonymous function</em>.
        </p>

        <p>
            This is a first glimpse at what I like to call "advanced"
            JavaScript, but let's take it step by step. For now, let's
            just accept that in JavaScript, we can pass a function as
            a parameter when calling another function. We can do this
            by assigning our function to a variable, which we then
            pass, or by defining the function to pass in-place.
        </p>

        <a name="how-function-passing-makes-our-http-server-work"></a>

        <h3>How function passing makes our HTTP server work</h3>

        <p>
            With this knowledge, let's get back to our minimalistic
            HTTP server:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br>http</span><span
                class="pun">.</span><span class="pln">createServer</span><span class="pun">(</span><span class="kwd">function</span><span
                class="pun">(</span><span class="pln">request</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/plain"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; response</span><span class="pun">.</span><span class="pln">write</span><span
                class="pun">(</span><span class="str">"Hello World"</span><span class="pun">);</span><span
                class="pln"><br>&nbsp; response</span><span class="pun">.</span><span class="pln">end</span><span
                class="pun">();</span><span class="pln"><br></span><span class="pun">}).</span><span
                class="pln">listen</span><span class="pun">(</span><span class="lit">8888</span><span
                class="pun">);</span></pre>

        <p>
            By now it should be clear what we are actually doing here:
            we pass the <em>createServer</em> function an anonymous
            function.
        </p>

        <p>
            We could achieve the same by refactoring our code to:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> onRequest</span><span class="pun">(</span><span class="pln">request</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/plain"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; response</span><span class="pun">.</span><span class="pln">write</span><span
                class="pun">(</span><span class="str">"Hello World"</span><span class="pun">);</span><span
                class="pln"><br>&nbsp; response</span><span class="pun">.</span><span class="pln">end</span><span
                class="pun">();</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>http</span><span
                class="pun">.</span><span class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span></pre>

        <p>
            Maybe now is a good moment to ask: Why are we doing it
            that way?
        </p>

        <a name="event-driven-callbacks"></a>

        <h3>Event-driven asynchronous callbacks</h3>

        <p>
            To understand why Node.js applications have to be written this way,
            we need to understand how Node.js executes our code. Node's
            approach isn't unique, but the underlying execution model is
            different from runtime environments like Python, Ruby, PHP or Java.
        </p>

        <p>
            Let's take a very simple piece of code like this:
        </p>

        <pre class="prettyprint lang-js">var result = database.query("SELECT * FROM hugetable");
console.log("Hello World");</pre>

        <p>
            Please ignore for now that we haven't actually talked about
            connecting to databases before - it's just an example. The
            first line queries a database for lots of rows, the second
            line puts "Hello World" to the console.
        </p>

        <p>
            Let's assume that the database query is really slow, that it has
            to read an awful lot of rows, which takes several seconds.
        </p>

        <p>
            The way we have written this code, the JavaScript interpreter of
            Node.js first has to read the complete result set from the
            database, and then it can execute the <em>console.log()</em>
            function.
        </p>

        <p>
            If this piece of code actually was, say, PHP, it would work the
            same way: read all the results at once, then execute the next line
            of code. If this code would be part of a web page script, the user
            would have to wait several seconds for the page to load.
        </p>

        <p>
            However, in the execution model of PHP, this would not become a
            "global" problem: the web server starts its own PHP process for
            every HTTP request it receives. If one of these requests results
            in the execution of a slow piece of code, it results in a slow
            page load for this particular user, but other users requesting
            other pages would not be affected.
        </p>

        <p>
            The execution model of Node.js is different - there is only one
            single process. If there is a slow database query somewhere in
            this process, this affects the whole process - everything comes
            to a halt until the slow query has finished.
        </p>

        <p>
            To avoid this, JavaScript, and therefore Node.js, introduces the
            concept of event-driven, asynchronous callbacks, by utilizing an
            event loop.
        </p>

        <p>
            We can understand this concept by analyzing a rewritten version
            of our problematic code:
        </p>

        <pre class="prettyprint lang-js">database.query("SELECT * FROM hugetable", function(rows) {
  var result = rows;
});
console.log("Hello World");</pre>

        <p>
            Here, instead of expecting <em>database.query()</em> to directly
            return a result to us, we pass it a second parameter, an anonymous
            function.
        </p>

        <p>
            In its previous form, our code was synchronous: <em>first</em>
            do the database query, and only when this is done, <em>then</em>
            write to the console.
        </p>

        <p>
            Now, Node.js can handle the database request asynchronously.
            Provided that <em>database.query()</em> is part of an asynchronous
            library, this is what Node.js does: just as before, it takes the
            query and sends it to the database. But instead of waiting for it
            to be finished, it makes a mental note that says "When at some
            point in the future the database server is done and sends the
            result of the query, then I have to execute the anonymous function
            that was passed to <em>database.query()</em>."
        </p>

        <p>
            Then, it immediately executes <em>console.log()</em>, and
            afterwards, it enters the event loop. Node.js continuously cycles
            through this loop again and again whenever there is nothing else
            to do, waiting for events. Events like, e.g., a slow database
            query finally delivering its results.
        </p>

        <p>
            This also explains why our HTTP server needs a function it can
            call upon incoming requests - if Node.js would start the server
            and then just pause, waiting for the next request, continuing
            only when it arrives, that would be highly inefficent. If a second
            user requests the server while it is still serving the first
            request, that second request could only be answered after the first
            one is done - as soon as you have more than a handful of HTTP
            requests per second, this wouldn't work at all.
        </p>

        <p>
            It's important to note that this asynchronous, single-threaded,
            event-driven execution model isn't an infinitely scalable
            performance unicorn with silver bullets attached. It is just one
            of several models, and it has its limitations, one being that as
            of now, Node.js is just one single process, and it can run on only
            one single CPU core. Personally, I find this model quite
            approachable, because it allows to write applications that have to
            deal with concurrency in an efficient and relatively
            straightforward manner.
        </p>

        <p>
            You might want to take the time to read Felix
            Geisendörfer's excellent post
            <a href="http://debuggable.com/posts/understanding-node-js:4bd98440-45e4-4a9a-8ef7-0f7ecbdd56cb">Understanding
                node.js</a>
            for additional background explanation.
        </p>

        <p>
            Let's play around a bit with this new concept. Can we prove
            that our code continues after creating the server, even if
            no HTTP request happened and the callback function we
            passed isn't called? Let's try it:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> onRequest</span><span class="pun">(</span><span class="pln">request</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request received."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello World"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>http</span><span class="pun">.</span><span class="pln">createServer</span><span
                class="pun">(</span><span class="pln">onRequest</span><span class="pun">).</span><span class="pln">listen</span><span
                class="pun">(</span><span class="lit">8888</span><span class="pun">);</span><span class="pln"><br><br>console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span></pre>

        <p>
            Note that I use <em>console.log</em> to output a text whenever
            the <em>onRequest</em> function (our callback) is triggered,
            and another text right <em>after</em> starting the HTTP server.
        </p>

        <p>
            When we start this (<em>node server.js</em>, as always), it
            will immediately output "Server has started." on the
            command line. Whenever we request our server (by opening
            <a href="http://localhost:8888/" rel="nofollow">http://localhost:8888/</a>

            in our browser), the message "Request received." is printed
            on the command line.
        </p>

        <p>
            Event-driven asynchronous server-side JavaScript with
            callbacks in action :-)
        </p>

        <p>
            (Note that our server will probably write "Request received."
            to STDOUT two times upon opening the page in a browser. That's
            because most browsers will try to load the favicon by requesting
            http://localhost:8888/favicon.ico whenever you open
            http://localhost:8888/).
        </p>

        <a name="how-our-server-handles-requests"></a>

        <h3>How our server handles requests</h3>

        <p>
            Ok, let's quickly analyze the rest of our server code, that
            is, the body of our callback function <em>onRequest()</em>.
        </p>

        <p>
            When the callback fires and our <em>onRequest()</em> function
            gets triggered, two parameters are passed into it:
            <em>request</em> and <em>response</em>.
        </p>

        <p>
            Those are objects, and you can use their methods to handle
            the details of the HTTP request that occured and to respond
            to the request (i.e., to actually send something over
            the wire back to the browser that requested your server).
        </p>

        <p>
            And our code does just that: Whenever a request is
            received, it uses the <em>response.writeHead()</em>
            function to send an HTTP status 200 and content-type in the
            HTTP response header, and the <em>response.write()</em>
            function to send the text "Hello World" in the HTTP
            response body.
        </p>

        <p>
            At last, we call <em>response.end()</em> to actually finish
            our response.
        </p>

        <p>
            At this point, we don't care for the details of the
            request, which is why we don't use the <em>request</em>
            object at all.
        </p>

        <a name="finding-a-place-for-our-server-module"></a>

        <h3>Finding a place for our server module</h3>

        <p>
            Ok, I promised we will get back to how to organize our
            application. We have the code for a very basic HTTP server in
            the file <em>server.js</em>, and I mentioned that it's common
            to have a main file called <em>index.js</em> which is used
            to bootstrap and start our application by making use of the
            other modules of the application (like the HTTP server module
            that lives in <em>server.js</em>).
        </p>

        <p>
            Let's talk about how to make server.js a real Node.js module
            that can be used by our yet-to-be-written <em>index.js</em>
            main file.
        </p>

        <p>
            As you may have noticed, we already used modules in our code,
            like this:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br></span><span class="pun">...</span><span
                class="pln"><br><br>http</span><span class="pun">.</span><span class="pln">createServer</span><span
                class="pun">(...);</span></pre>

        <p>
            Somewhere within Node.js lives a module called "http", and we can
            make use of it in our own code by requiring it and assigning
            the result of the require to a local variable.
        </p>

        <p>
            This makes our local variable an object that carries all the
            public methods the <em>http</em> module provides.
        </p>

        <p>
            It's common practice to choose the name of the module for the
            name of the local variable, but we are free to choose whatever
            we like:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> foo </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br></span><span class="pun">...</span><span
                class="pln"><br><br>foo</span><span class="pun">.</span><span class="pln">createServer</span><span
                class="pun">(...);</span></pre>

        <p>
            Fine, it's clear how to make use of internal Node.js modules. How
            do we create our own modules, and how do we use them?
        </p>

        <p>
            Let's find out by turning our <em>server.js</em> script into a
            real module.
        </p>

        <p>
            Turns out, we don't have to change that much. Making some code
            a module means we need to <em>export</em> those parts of its
            functionality that we want to provide to scripts that require
            our module.
        </p>

        <p>
            For now, the functionality our HTTP server needs to export is
            simple: scripts requiring our server module simply need to
            start the server.
        </p>

        <p>
            To make this possible, we will put our server code into a
            function named <em>start</em>, and we will export this
            function:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; </span><span class="kwd">function</span><span class="pln"> onRequest</span><span
                class="pun">(</span><span class="pln">request</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request received."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello World"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br><br>&nbsp; http</span><span class="pun">.</span><span
                class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            This way, we can now create our main file <em>index.js</em>,
            and start our HTTP there, although the code for the server is
            still in our <em>server.js</em> file.
        </p>

        <p>
            Create a file <em>index.js</em> with the following content:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> server </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"./server"</span><span
                class="pun">);</span><span class="pln"><br><br>server</span><span class="pun">.</span><span class="pln">start</span><span
                class="pun">();</span></pre>

        <p>
            As you can see, we can use our server module just like any
            internal module: by requiring its file and assigning it to
            a variable, its exported functions become available to us.
        </p>

        <p>
            That's it. We can now start our app via our main script, and it
            still does exactly the same:
        </p>
        <pre>node index.js</pre>

        <p>
            Great, we now can put the different parts of our application
            into different files and wire them together by making them
            modules.
        </p>

        <p>
            We still have only the very first part of our application in
            place: we can receive HTTP requests. But we need to do
            something with them - depending on which URL the browser
            requested from our server, we need to react differently.
        </p>

        <p>
            For a very simple application, you could do this directly
            within the callback function <em>onRequest()</em>. But as I said,
            let's add a bit more abstraction in order to make our example
            application a bit more interesting.
        </p>

        <p>
            Making different HTTP requests point at different parts of our
            code is called "routing" - well, then, let's create a module
            called <em>router</em>.
        </p>

        <a name="whats-needed-to-route-requests"></a>

        <h3>What's needed to "route" requests?</h3>

        <p>
            We need to be able to feed the requested URL and possible
            additional GET and POST parameters into our router, and based
            on these the router then needs to be able to decide which code
            to execute (this "code to execute" is the third part of our
            application: a collection of request handlers that do the
            actual work when a request is received).
        </p>

        <p>
            So, we need to look into the HTTP requests and extract the
            requested URL as well as the GET/POST parameters from them.
            It could be argued if that should be part of the router or
            part of the server (or even a module of its own), but let's
            just agree on making it part of our HTTP server for now.
        </p>

        <p>
            All the information we need is available through the
            <em>request</em> object which is passed as the first parameter
            to our callback function <em>onRequest()</em>. But to interpret
            this information, we need some additional Node.js modules, namely
            <em>url</em> and <em>querystring</em>.
        </p>

        <a name="head20"></a>
        <p>
            The <em>url</em> module provides methods which allow us to
            extract the different parts of a URL (like e.g. the requested
            path and query string), and <em>querystring</em> can in turn be
            used to parse the query string for request parameters:
        </p>
<pre> url.parse(string).query
                                           |
           url.parse(string).pathname |
                       | |
                       | |
                     ------ -------------------
http://localhost:8888/start?foo=bar&amp;hello=world
                                --- -----
                                 | |
                                 | |
              querystring(string)["foo"] |
                                            |
                         querystring(string)["hello"]
</pre>

        <p>
            We can, of course, also use <em>querystring</em> to parse the
            body of a POST request for parameters, as we will see
            later.
        </p>

        <p>
            Let's now add to our <em>onRequest()</em> function the logic
            needed to find out which URL path the browser requested:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br></span><span
                class="kwd">var</span><span class="pln"> url </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"url"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; </span><span class="kwd">function</span><span class="pln"> onRequest</span><span
                class="pun">(</span><span class="pln">request</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> pathname </span><span class="pun">=</span><span class="pln"> url</span><span
                class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span
                class="pln">request</span><span class="pun">.</span><span class="pln">url</span><span
                class="pun">).</span><span class="pln">pathname</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">" received."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello World"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br><br>&nbsp; http</span><span class="pun">.</span><span
                class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            Fine. Our application can now distinguish requests based on the
            URL path requested - this allows us to map requests to our
            request handlers based on the URL path using our (yet to be
            written) router.
        </p>

        <p>
            In the context of our application, it simply means that we will
            be able to have requests for the <em>/start</em> and
            <em>/upload</em> URLs handled by different parts of our
            code. We will see how everything fits together soon.
        </p>

        <p>
            Ok, it's time to actually write our router. Create a new file
            called <em>router.js</em>, with the following content:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> route</span><span
                class="pun">(</span><span class="pln">pathname</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"About to route a request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">route </span><span class="pun">=</span><span
                class="pln"> route</span><span class="pun">;</span></pre>

        <p>
            Of course, this code basically does nothing, but that's ok for
            now. Let's first see how to wire together this router with our
            server before putting more logic into the router.
        </p>

        <p>
            Our HTTP server needs to know about and make use of our router.
            We could hard-wire this dependency into the server, but because
            we learned the hard way from our experience with other
            programming languages, we are going to loosely couple server
            and router by injecting this dependency (you may want to read
            <a href="http://martinfowler.com/articles/injection.html">Martin Fowlers excellent post on Dependency Injection</a>
            for background information).
        </p>

        <p>
            Let's first extend our server's <em>start()</em> function in
            order to enable us to pass the route function to be used by
            parameter:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br></span><span
                class="kwd">var</span><span class="pln"> url </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"url"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">(</span><span class="pln">route</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; </span><span class="kwd">function</span><span class="pln"> onRequest</span><span
                class="pun">(</span><span class="pln">request</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> pathname </span><span class="pun">=</span><span class="pln"> url</span><span
                class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span
                class="pln">request</span><span class="pun">.</span><span class="pln">url</span><span
                class="pun">).</span><span class="pln">pathname</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">" received."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; &nbsp; route</span><span class="pun">(</span><span
                class="pln">pathname</span><span class="pun">);</span><span
                class="pln"><br><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello World"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br><br>&nbsp; http</span><span class="pun">.</span><span
                class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            And let's extend our <em>index.js</em> accordingly, that is,
            injecting the route function of our router into the server:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> server </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"./server"</span><span
                class="pun">);</span><span class="pln"><br></span><span class="kwd">var</span><span
                class="pln"> router </span><span class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"./router"</span><span class="pun">);</span><span class="pln"><br><br>server</span><span
                class="pun">.</span><span class="pln">start</span><span class="pun">(</span><span
                class="pln">router</span><span class="pun">.</span><span class="pln">route</span><span
                class="pun">);</span><span class="pln"><br></span></pre>

        <p>
            Again, we are passing a function, which by now isn't any news
            for us.
        </p>

        <p>
            If we start our application now (<em>node index.js,
            as always</em>), and request an URL, you can now see from the
            application's output that our HTTP server makes use of our
            router and passes it the requested pathname:
        </p>
        <pre>bash$ node index.js
Request for /foo received.
About to route a request for /foo</pre>

        <p>
            (I omitted the rather annoying output for the /favicon.ico
            request).
        </p>

        <a name="execution-in-the-kongdom-of-verbs"></a>

        <h3>Execution in the kingdom of verbs</h3>

        <p>
            May I once again stray away for a while and talk about
            functional programming again?
        </p>

        <p>
            Passing functions is not only a technical consideration.
            With regard to software design, it's almost philosophical.
            Just think about it: in our index file, we could have passed
            the <em>router</em> object into the server, and the server
            could have called this object's <em>route</em> function.
        </p>

        <p>
            This way, we would have passed a <em>thing</em>, and the server
            would have used this thing to <em>do</em> something. Hey,
            router thing, could you please route this for me?
        </p>

        <p>
            But the server doesn't need the thing. It only needs to get
            something <em>done</em>, and to get something done, you don't
            need things at all, you need <em>actions</em>. You don't need
            <em>nouns</em>, you need <em>verbs</em>.
        </p>

        <p>
            Understanding the fundamental mind-shift that's at the core of
            this idea is what made me really understand functional
            programming.
        </p>

        <p>
            And I did understand it when reading Steve Yegge's masterpiece
            <a href="http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html">Execution in the Kingdom of Nouns</a>.
            Go read it now, really. It's one of the best writings related
            to software I ever had the pleasure to encounter.
        </p>

        <a name="routing-to-real-request-handlers"></a>

        <h3>Routing to real request handlers</h3>

        <p>
            Back to business. Our HTTP server and our request router are
            now best friends and talk to each other as we intended.
        </p>

        <p>
            Of course, that's not enough. "Routing" means, we want to
            handle requests to different URLs differently. We would like to
            have the "business logic" for requests to <em>/start</em>
            handled in another function than requests to <em>/upload</em>.
        </p>

        <p>
            Right now, the routing "ends" in the router, and the router is
            not the place to actually "do" something with the requests,
            because that wouldn't scale well once our application becomes
            more complex.
        </p>

        <a name="continuereading"></a>
        <p>
            Let's call these functions, where requests are routed to,
            <em>request handlers</em>. And let's tackle those next, because
            unless we have these in place there isn't much sense in doing
            anything with the router for now.
        </p>
        </div>

        <div id="salespitch">
          <div id="bubble">
            <img id="authorimage" src="manuelkiessling.jpg" width="160" height="160"/>
            <p>
              <br/>
              Hi there! Sorry to interrupt you.
            </p>
            <p>
              My name is Manuel Kiessling, I'm the author of this book.
            </p>
            <p>
              If you have read that far, I guess I may assume that you like
              the book. I'm pretty sure you also like the fact that it's free,
              which is totally fine, and you can continue reading it for free,
              which also is totally fine.
            </p>
            <p>
              However, I would like you to consider buying the eBook version
              of the book. It's a beautifully crafted package including a PDF,
              an ePub, and a MOBI file, which means you can read it on all
              kinds of eReaders out there like the Amazon Kindle, the Nook, or
              the Sony Reader.
            </p>
            <p>
              But the best thing about it is that it comes bundled with another
              great Node.js book: <em>"Hands-on Node.js"</em> by Pedro Teixeira. It's a
              complete reference that explains all the Node.js modules in great
              detail - it's perfect to dig deeper once you finished <em>The Node
              Beginner Book</em>.
            </p>
            <p>
              Both books together would cost a total of $21.98, but we are offering
              it as a bundle for only <strong>$9.99</strong>.
              You can download it immediately, it's
              completely DRM-free, and you will receive any future updates for
              both books for free.
            </p>
            <p>
              So, here are the two choices you have right now:
            </p>
            <div class="box">
              <a href="buy-bundle/salespitch.html"><img src="the_node_beginner_book_cover_small.png" height="86" width="57" /></a>
              <a href="buy-bundle/salespitch.html"><img src="hands-on_node.js_cover.png" height="86" width="57" /></a>
              <br/>
              <div class="subinfo">
                226 pages in total<br/>
                DRM-free<br/>
                Free updates<br/>
                <strong>Only $9.99</strong>
              </div>
              <a class="buttonlink" href="buy-bundle/salespitch.html">
                <div class="button">Buy this<br />bundle now</div>
              </a>
            </div>
            <div class="orbox">
              <strong>OR</strong>
            </div>
            <div class="box">
              <script type="text/javascript">
              var showHiddenHalf = function() {
                document.getElementById('hiddenhalf').style.opacity = '1.0';
                document.getElementById('salespitch').style.display = 'none';
                return false;
              };
              </script>
              <a href="#continuereading" onclick="showHiddenHalf();">Continue reading<br/>the free version</a>
            </div>
          </div>
          <br clear="all"/>
        </div>

        <div id="hiddenhalf">
        <p>
            New application part, new module - no surprise here. Let's
            create a module called requestHandlers, add a placeholder
            function for every request handler, and export these as
            methods of the module:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span
                class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> upload</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            This allows us to wire the request handlers into the router,
            giving our router something to route to.
        </p>

        <p>
            At this point we need to make a decision: do we hard-code usage
            of the requestHandlers module into the router, or do we want a
            bit more dependency injection? Although dependency injection,
            like every other pattern, shouldn't be used only for the sake
            of using it, in this case it makes sense to loosely couple the
            router and its request handlers, and thus making the router
            really reusable.
        </p>

        <p>
            This means we need to pass the request handlers from our server
            into our router, but this feels even more wrong, which is why
            we should go the whole way and pass them to the server from our
            main file, and passing it on to the router from there.
        </p>

        <p>
            How are we going to pass them? Right now we have two handlers,
            but in a real application, this number is going to increase and
            vary, and we sure don't want to fiddle around mapping requests
            to handlers in the router anytime a new URL / request handler
            is added. And having some
            <em>if request == x then call handler y</em> in the router
            would be more than ugly.
        </p>

        <p>
            A varying number of items, each mapped to a string (the
            requested URL)? Well, sounds like an associative array would be
            a perfect fit.
        </p>

        <p>
            Well, this finding is slightly disappointed by the fact that
            JavaScript doesn't provide associative array - or does it?
            Turns out, it's actually objects that we want to use if we need
            an associative array!
        </p>

        <p>
            There's a nice introduction to this at
            <a href="http://msdn.microsoft.com/en-us/magazine/cc163419.aspx">http://msdn.microsoft.com/en-us/magazine/cc163419.aspx</a>,
            let me quote the relevant part:
        </p>
        <blockquote>
            <p>
                In C++ or C#, when we’re talking about objects, we're
                referring to instances of classes or structs. Objects have
                different properties and methods, depending on which
                templates (that is, classes) they are instantiated from.
                That's not the case with JavaScript objects. In JavaScript,
                objects are just collections of name/value pairs - think of a
                JavaScript object as a dictionary with string keys.
            </p>
        </blockquote>

        <p>
            If JavaScript objects are just collections of name/value pairs,
            how can they have methods? Well, the values can be strings,
            numbers etc. - or functions!
        </p>

        <p>
            Ok, now finally back to the code. We decided we want to pass
            the list of requestHandlers as an object, and in order to
            achieve loose coupling we want to inject this object into the
            <em>route()</em>.
        </p>

        <p>
            Let's start with putting the object together in our main file
            <em>index.js</em>:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> server </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"./server"</span><span
                class="pun">);</span><span class="pln"><br></span><span class="kwd">var</span><span
                class="pln"> router </span><span class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"./router"</span><span class="pun">);</span><span class="pln"><br></span><span class="kwd">var</span><span
                class="pln"> requestHandlers </span><span class="pun">=</span><span class="pln"> require</span><span
                class="pun">(</span><span class="str">"./requestHandlers"</span><span class="pun">);</span><span
                class="pln"><br><br></span><span class="kwd">var</span><span class="pln"> handle </span><span
                class="pun">=</span><span class="pln"> </span><span class="pun">{}</span><span
                class="pln"><br>handle</span><span class="pun">[</span><span class="str">"/"</span><span
                class="pun">]</span><span class="pln"> </span><span class="pun">=</span><span class="pln"> requestHandlers</span><span
                class="pun">.</span><span class="pln">start</span><span class="pun">;</span><span class="pln"><br>handle</span><span
                class="pun">[</span><span class="str">"/start"</span><span class="pun">]</span><span
                class="pln"> </span><span class="pun">=</span><span class="pln"> requestHandlers</span><span
                class="pun">.</span><span class="pln">start</span><span class="pun">;</span><span class="pln"><br>handle</span><span
                class="pun">[</span><span class="str">"/upload"</span><span class="pun">]</span><span
                class="pln"> </span><span class="pun">=</span><span class="pln"> requestHandlers</span><span
                class="pun">.</span><span class="pln">upload</span><span class="pun">;</span><span class="pln"><br><br>server</span><span
                class="pun">.</span><span class="pln">start</span><span class="pun">(</span><span
                class="pln">router</span><span class="pun">.</span><span class="pln">route</span><span
                class="pun">,</span><span class="pln"> handle</span><span class="pun">);</span></pre>

        <p>
            Although <em>handle</em> is more of a "thing" (a collection of
            request handlers), I propose we name it like a verb, because
            this will result in a fluent expression in our router, as we
            will see soon.
        </p>

        <p>
            As you can see, it's really simple to map different URLs to the
            same request handler: by adding a key/value pair of
            <em>"/"</em> and <em>requestHandlers.start</em>, we can express
            in a nice and clean way that not only requests to
            <em>/start</em>, but also requests to <em>/</em> shall be
            handled by the <em>start</em> handler.
        </p>

        <p>
            After defining our object, we pass it into the server as an
            additional parameter. Let's change our <em>server.js</em> to
            make use of it:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br></span><span
                class="kwd">var</span><span class="pln"> url </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"url"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">(</span><span class="pln">route</span><span
                class="pun">,</span><span class="pln"> handle</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; </span><span class="kwd">function</span><span
                class="pln"> onRequest</span><span class="pun">(</span><span class="pln">request</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> pathname </span><span class="pun">=</span><span class="pln"> url</span><span
                class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span
                class="pln">request</span><span class="pun">.</span><span class="pln">url</span><span
                class="pun">).</span><span class="pln">pathname</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">" received."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; &nbsp; route</span><span class="pun">(</span><span
                class="pln">handle</span><span class="pun">,</span><span class="pln"> pathname</span><span class="pun">);</span><span
                class="pln"><br><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello World"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br><br>&nbsp; http</span><span class="pun">.</span><span
                class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            We've added the <em>handle</em> parameter to our
            <em>start()</em> function, and pass the handle object on to
            the <em>route()</em> callback, as its first parameter.
        </p>

        <p>
            Let's change the <em>route()</em> function accordingly, in our
            <em>router.js</em> file:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> route</span><span
                class="pun">(</span><span class="pln">handle</span><span class="pun">,</span><span
                class="pln"> pathname</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span class="str">"About to route a request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">if</span><span
                class="pln"> </span><span class="pun">(</span><span class="kwd">typeof</span><span
                class="pln"> handle</span><span class="pun">[</span><span class="pln">pathname</span><span
                class="pun">]</span><span class="pln"> </span><span class="pun">===</span><span
                class="pln"> </span><span class="str">'function'</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; handle</span><span
                class="pun">[</span><span class="pln">pathname</span><span class="pun">]();</span><span class="pln"><br>&nbsp; </span><span
                class="pun">}</span><span class="pln"> </span><span class="kwd">else</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"No request handler found for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">route </span><span class="pun">=</span><span
                class="pln"> route</span><span class="pun">;</span></pre>

        <p>
            What we do here is, we check if a request handler for the given
            pathname exists, and if it does, we simply call the according
            function. Because we can access our request handler functions
            from our object just as we would access an element of an
            associative array, we have this nice fluent
            <em>handle[pathname]();</em> expression I talked about earlier:
            "Please, <em>handle</em> this <em>pathname</em>".
        </p>

        <p>
            Ok, that's all we need to wire server, router, and request
            handlers together! When starting our application and requesting
            <a href="http://localhost:8888/start" rel="nofollow">http://localhost:8888/start</a>

            in our browser, we can prove that the correct request handler
            was indeed called:
        </p>
        <pre>Server has started.
Request for /start received.
About to route a request for /start
Request handler 'start' was called.</pre>

        <p>
            And opening <a href="http://localhost:8888/" rel="nofollow">http://localhost:8888/</a>
            in our browser proves that these requests, too, are indeed handled by
            the <em>start</em> request handler:
        </p>
        <pre>Request for / received.
About to route a request for /
Request handler 'start' was called.</pre>

        <a name="making-the-request-handlers-respond"></a>

        <h3>Making the request handlers respond</h3>

        <p>
            Beautiful. Now if only the request handlers could actually send
            something back to the browser, that would be even better,
            right?
        </p>

        <p>
            Remember, the "Hello World" your browser displays upon
            requesting a page still comes from the <em>onRequest</em>

            function in our <em>server.js</em> file.
        </p>

        <p>
            "Handling request" means "answering requests" after all, thus
            we need to enable our request handlers to speak with the
            browser just like our <em>onRequest</em> function does.
        </p>

        <a name="how-to-not-do-it"></a>

        <h4>How to not do it</h4>

        <p>
            The straight-forward approach we - as developers with a
            background in PHP or Ruby - might want to follow is actually
            very deceitful: it works like a charm, seems to make a lot of
            sense, and then suddenly screws things up when we don't expect
            it.
        </p>

        <p>
            What I mean by "straight-forward approach" is this: make the
            request handlers <em>return()</em> the content they want to
            display to the user, and send this response data in the
            <em>onRequest</em> function back to the user.
        </p>

        <p>
            Let's just do this, and then see why it's not such an overly
            good idea.
        </p>

        <p>
            We start with the request handlers and make them return what we
            would like to display in the browser. We need to change
            <em>requestHandlers.js</em> to this:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">return</span><span
                class="pln"> </span><span class="str">"Hello Start"</span><span class="pun">;</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> upload</span><span class="pun">()</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span
                class="str">"Request handler 'upload' was called."</span><span class="pun">);</span><span
                class="pln"><br>&nbsp; </span><span class="kwd">return</span><span class="pln"> </span><span
                class="str">"Hello Upload"</span><span class="pun">;</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>exports</span><span class="pun">.</span><span class="pln">start </span><span
                class="pun">=</span><span class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            Good. Likewise, the router needs to return to the server what
            the request handlers return to him. We therefore need to edit
            <em>router.js</em> like this:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> route</span><span
                class="pun">(</span><span class="pln">handle</span><span class="pun">,</span><span
                class="pln"> pathname</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span class="str">"About to route a request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">if</span><span
                class="pln"> </span><span class="pun">(</span><span class="kwd">typeof</span><span
                class="pln"> handle</span><span class="pun">[</span><span class="pln">pathname</span><span
                class="pun">]</span><span class="pln"> </span><span class="pun">===</span><span
                class="pln"> </span><span class="str">'function'</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">return</span><span class="pln"> handle</span><span class="pun">[</span><span class="pln">pathname</span><span
                class="pun">]();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"> </span><span class="kwd">else</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span class="str">"No request handler found for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="kwd">return</span><span
                class="pln"> </span><span class="str">"404 Not found"</span><span class="pun">;</span><span class="pln"><br>&nbsp; </span><span
                class="pun">}</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">route </span><span class="pun">=</span><span
                class="pln"> route</span><span class="pun">;</span></pre>

        <p>
            As you can see, we also return some text if the request could
            not be routed.
        </p>

        <p>
            And last but not least, we need to refactor our server to make
            it respond to the browser with the content the request handlers
            returned via the router, transforming <em>server.js</em> into:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br></span><span
                class="kwd">var</span><span class="pln"> url </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"url"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">(</span><span class="pln">route</span><span
                class="pun">,</span><span class="pln"> handle</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; </span><span class="kwd">function</span><span
                class="pln"> onRequest</span><span class="pun">(</span><span class="pln">request</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> pathname </span><span class="pun">=</span><span class="pln"> url</span><span
                class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span
                class="pln">request</span><span class="pun">.</span><span class="pln">url</span><span
                class="pun">).</span><span class="pln">pathname</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">" received."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; &nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/plain"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="kwd">var</span><span class="pln"> content </span><span
                class="pun">=</span><span class="pln"> route</span><span class="pun">(</span><span
                class="pln">handle</span><span class="pun">,</span><span class="pln"> pathname</span><span
                class="pun">)</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="pln">content</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br><br>&nbsp; http</span><span class="pun">.</span><span
                class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            If we start our rewritten application, everything works like
            a charm: requesting <a href="http://localhost:8888/start" rel="nofollow">http://localhost:8888/start</a>
            results in "Hello Start" being displayed in the browser,
            requesting <a href="http://localhost:8888/upload" rel="nofollow">http://localhost:8888/upload</a>
            gives us "Hello Upload", and <a href="http://localhost:8888/foo" rel="nofollow">http://localhost:8888/foo</a>
            produces "404 Not found".
        </p>

        <p>
            Ok, then why is that a problem? The short answer: because we
            will run into problems if one of the request handlers wants to make
            use of a non-blocking operation in the future.
        </p>

        <p>
            Let's take a bit more time for the long answer.
        </p>

        <a name="blocking-and-non-blocking"></a>

        <h4>Blocking and non-blocking</h4>

        <p>
            As said, the problems will arise when we include non-blocking
            operations in the request handlers. But let's talk about
            blocking operations first, then about non-blocking operations.
        </p>

        <p>
            And instead of trying to explain what "blocking" and
            "non-blocking" means, let's demonstrate ourselves what happens
            if we add a blocking operation to our request handlers.
        </p>

        <p>
            To do this, we will modify our <em>start</em> request handler
            to make it wait 10 seconds before returning its "Hello Start"
            string. Because there is no such thing as <em>sleep()</em> in
            JavaScript, we will use a clever hack for that.
        </p>

        <p>
            Please modify <em>requestHandlers.js</em> as follows:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; </span><span class="kwd">function</span><span
                class="pln"> sleep</span><span class="pun">(</span><span class="pln">milliSeconds</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> startTime </span><span class="pun">=</span><span
                class="pln"> </span><span class="kwd">new</span><span class="pln"> </span><span
                class="typ">Date</span><span class="pun">().</span><span class="pln">getTime</span><span
                class="pun">();</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="kwd">while</span><span
                class="pln"> </span><span class="pun">(</span><span class="kwd">new</span><span
                class="pln"> </span><span class="typ">Date</span><span class="pun">().</span><span
                class="pln">getTime</span><span class="pun">()</span><span class="pln"> </span><span
                class="pun">&lt;</span><span class="pln"> startTime </span><span class="pun">+</span><span class="pln"> milliSeconds</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br><br>&nbsp; sleep</span><span class="pun">(</span><span class="lit">10000</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">return</span><span
                class="pln"> </span><span class="str">"Hello Start"</span><span class="pun">;</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> upload</span><span class="pun">()</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span
                class="str">"Request handler 'upload' was called."</span><span class="pun">);</span><span
                class="pln"><br>&nbsp; </span><span class="kwd">return</span><span class="pln"> </span><span
                class="str">"Hello Upload"</span><span class="pun">;</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>exports</span><span class="pun">.</span><span class="pln">start </span><span
                class="pun">=</span><span class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            Just to make clear what that does: when the function
            <em>start()</em> is called, Node.js waits 10 seconds and only then
            returns "Hello Start". When calling <em>upload()</em>, it
            returns immediately, just like before.
        </p>

        <p>
            (Of course, you should imagine that instead of sleeping for
            10 seconds, there would be a real life blocking operation in
            <em>start()</em>, like some sort of long-running computation.)
        </p>

        <p>
            Let's see what this change does.
        </p>

        <p>
            As always, we need to restart our server. This time, I ask you
            to follow a slightly complex "protocol" in order to see what
            happens: First, open two browser windows or tabs. In the first
            browser window, please enter <a href="http://localhost:8888/start" rel="nofollow">http://localhost:8888/start</a>
            into the address bar, but do not yet open this url!
        </p>

        <p>
            In the second browser window's address bar, enter <a href="http://localhost:8888/upload" rel="nofollow">http://localhost:8888/upload</a>,
            and again, please do not yet hit enter.
        </p>

        <p>
            Now, do as follows: hit enter on the first window ("/start"),
            then quickly change to the second window ("/upload") and hit
            enter, too.
        </p>

        <p>
            What you will notice is this: The /start URL takes 10 seconds
            to load, as we would expect. But the /upload URL <em>also</em>
            takes 10 seconds to load, although there is no <em>sleep()</em>
            in the according request handler.
        </p>

        <p>
            Why? Because <em>start()</em> contains a blocking operation.
            We already talked about Node's execution model - expensive
            operations are ok, but we must take care to not block the Node.js
            process with them. Instead, whenever expensive operations must be
            executed, these must be put in the background, and their events
            must be handled by the event loop.
        </p>

        <p>
            And we will now see why the way we constructed the "request
            handler response handling" in our application doesn't allow us
            to make proper use of non-blocking operations.
        </p>

        <p>
            Once again, let's try to experience the problem first-hand by
            modifying our application.
        </p>

        <p>
            We are going to use our <em>start</em> request handler for this
            again. Please modify it to reflect the following (file
            <em>requestHandlers.js</em>):
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> exec </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span class="str">"child_process"</span><span
                class="pun">).</span><span class="pln">exec</span><span class="pun">;</span><span
                class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">var</span><span class="pln"> content </span><span
                class="pun">=</span><span class="pln"> </span><span class="str">"empty"</span><span class="pun">;</span><span
                class="pln"><br><br>&nbsp; exec</span><span class="pun">(</span><span class="str">"ls -lah"</span><span
                class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span
                class="pln"> </span><span class="pun">(</span><span class="pln">error</span><span
                class="pun">,</span><span class="pln"> stdout</span><span class="pun">,</span><span
                class="pln"> stderr</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; &nbsp; content </span><span class="pun">=</span><span
                class="pln"> stdout</span><span class="pun">;</span><span class="pln"><br>&nbsp; </span><span
                class="pun">});</span><span class="pln"><br><br>&nbsp; </span><span class="kwd">return</span><span
                class="pln"> content</span><span class="pun">;</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> upload</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">return</span><span
                class="pln"> </span><span class="str">"Hello Upload"</span><span class="pun">;</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            As you can see, we just introduced a new Node.js module,
            <em>child_process</em>. We did so because it allows us to make
            use of a very simple yet useful non-blocking operation:
            <em>exec()</em>.
        </p>

        <p>
            What <em>exec()</em> does is, it executes a shell command from
            within Node.js. In this example, we are going to use it to get
            a list of all files in the current directory ("ls -lah"),
            allowing us to display this list in the browser of a user
            requesting the <em>/start</em> URL.
        </p>

        <p>
            What the code does is straightforward: create a new variable
            <em>content</em> (with an initial value of "empty"), execute
            "ls -lah", fill the variable with the result, and return it.
        </p>

        <p>
            As always, we will start our application, and visit
            <a href="http://localhost:8888/start" rel="nofollow">http://localhost:8888/start</a>.
        </p>

        <p>
            Which loads a beautiful web page that displays the string
            "empty". What's going wrong here?
        </p>

        <p>
            Well, as you may have already guessed, <em>exec()</em> does its
            magic in a non-blocking fashion. That's a good thing, because
            this way we can execute very expensive shell operations (like,
            e.g., copying huge files around or similar stuff) without
            forcing our application into a full stop as the blocking
            <em>sleep</em> operation did.
        </p>

        <p>
            (If you would like to prove this, replace "ls -lah" with a
            more expensive operation like "find /").
        </p>

        <p>
            But we aren't exactly happy with our elegant non-blocking
            operation, when our browser doesn't display its result, right?
        </p>

        <p>
            Well, then, let's fix it. And while we are at it, let's try to
            understand why the current architecture doesn't work.
        </p>

        <p>
            The problem is that <em>exec()</em>, in order to work
            non-blocking, makes use of a callback function.
        </p>

        <p>
            In our example, it's an anonymous function which is passed as
            the second parameter to the <em>exec()</em> function call:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> </span><span
                class="pun">(</span><span class="pln">error</span><span class="pun">,</span><span
                class="pln"> stdout</span><span class="pun">,</span><span class="pln"> stderr</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; content </span><span
                class="pun">=</span><span class="pln"> stdout</span><span class="pun">;</span><span
                class="pln"><br></span><span class="pun">}</span></pre>

        <p>
            And herein lies the root of our problem: our own code is
            executed synchronous, which means that immediately after
            calling <em>exec()</em>, Node.js continues to execute
            <em>return content;</em>. At this point, <em>content</em> is
            still "empty", due to the fact that the callback function
            passed to <em>exec()</em> has not yet been called - because
            <em>exec()</em> operates asynchronous.
        </p>

        <p>
            Now, "ls -lah" is a very inexpensive and fast operation (unless
            there are millions of files in the directory). Which is why the
            callback is called relatively expeditious - but it nevertheless
            happens asynchronously.
        </p>

        <p>
            Thinking about a more expensive command makes this more
            obvious: "find /" takes about 1 minute on my
            machine, but if I replace "ls -lah" with "find /" in the
            request handler, I still immediately receive an HTTP response
            when opening the /start URL - it's clear that <em>exec()</em>
            does something in the background, while Node.js itself
            continues with the application, and we may assume that the
            callback function we passed into <em>exec()</em> will be called
            only when the "find /" command has finished running.
        </p>

        <p>
            But how can we achieve our goal, i.e. showing the user a list
            of files in the current directory?
        </p>

        <p>
            Well, after learning how to <em>not</em> do it, let's discuss
            how to make our request handlers respond to browser requests
            the right way.
        </p>

        <a name="responding-request-handlers-with-non-blocking-operations"></a>

        <h4>Responding request handlers with non-blocking operations</h4>

        <p>
            I've just used the phrase "the right way". Dangerous stuff.
            Quite often, there is no single "right way".
        </p>

        <p>
            But one possible solution for this is, as often with Node.js,
            to pass functions around. Let's examine this.
        </p>

        <p>
            Right now, our application is able to transport the content
            (which the request handlers would like to display to the user)
            from the request handlers to the HTTP server by returning it
            up through the layers of the application (request handler -&gt;
            router -&gt; server).
        </p>

        <p>
            Our new approach is as follows: instead of bringing the content
            to the server, we will bring the server to the content. To be
            more precise, we will inject the <em>response</em> object (from
            our server's callback function <em>onRequest()</em>) through
            the router into the request handlers. The handlers will then be
            able to use this object's functions to respond to requests
            themselves.
        </p>

        <p>
            Enough explanation, here is the step by step recipe on how to
            change our application.
        </p>

        <p>
            Let's start with our <em>server.js</em>:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br></span><span
                class="kwd">var</span><span class="pln"> url </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"url"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">(</span><span class="pln">route</span><span
                class="pun">,</span><span class="pln"> handle</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; </span><span class="kwd">function</span><span
                class="pln"> onRequest</span><span class="pun">(</span><span class="pln">request</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> pathname </span><span class="pun">=</span><span class="pln"> url</span><span
                class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span
                class="pln">request</span><span class="pun">.</span><span class="pln">url</span><span
                class="pun">).</span><span class="pln">pathname</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">" received."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; &nbsp; route</span><span class="pun">(</span><span
                class="pln">handle</span><span class="pun">,</span><span class="pln"> pathname</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">);</span><span class="pln"><br>&nbsp; </span><span
                class="pun">}</span><span class="pln"><br><br>&nbsp; http</span><span class="pun">.</span><span
                class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            Instead of expecting a return value from the <em>route()</em>
            function, we pass it a third parameter, our <em>response</em>
            object. Furthermore, we removed any <em>response</em> method
            calls from the <em>onRequest()</em> handler, because we now
            expect <em>route</em> to take care of that.
        </p>

        <p>
            Next comes <em>router.js</em>:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> route</span><span
                class="pun">(</span><span class="pln">handle</span><span class="pun">,</span><span
                class="pln"> pathname</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"About to route a request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">if</span><span
                class="pln"> </span><span class="pun">(</span><span class="kwd">typeof</span><span
                class="pln"> handle</span><span class="pun">[</span><span class="pln">pathname</span><span
                class="pun">]</span><span class="pln"> </span><span class="pun">===</span><span
                class="pln"> </span><span class="str">'function'</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; handle</span><span
                class="pun">[</span><span class="pln">pathname</span><span class="pun">](</span><span class="pln">response</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"> </span><span class="kwd">else</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; console</span><span class="pun">.</span><span
                class="pln">log</span><span class="pun">(</span><span class="str">"No request handler found for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">404</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"404 Not found"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">route </span><span class="pun">=</span><span
                class="pln"> route</span><span class="pun">;</span></pre>

        <p>
            Same pattern: instead of expecting a return value from our
            request handlers, we pass the <em>response</em> object on.
        </p>

        <p>
            If no request handler can be used, we now take care of
            responding with a proper "404" header and body ourselves.
        </p>

        <p>
            And last but not least, we modify <em>requestHandlers.js</em>:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> exec </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span class="str">"child_process"</span><span
                class="pun">).</span><span class="pln">exec</span><span class="pun">;</span><span
                class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; exec</span><span class="pun">(</span><span
                class="str">"ls -lah"</span><span class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span
                class="pln"> </span><span class="pun">(</span><span class="pln">error</span><span
                class="pun">,</span><span class="pln"> stdout</span><span class="pun">,</span><span
                class="pln"> stderr</span><span class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="pln">stdout</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">});</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> upload</span><span class="pun">(</span><span class="pln">response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello Upload"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>exports</span><span class="pun">.</span><span class="pln">start </span><span
                class="pun">=</span><span class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            Our handler functions need to accept the response parameter,
            and have to make use of them in order to respond to the
            request directly.
        </p>

        <p>
            The <em>start</em> handler will respond from within the
            anonymous <em>exec()</em> callback, and the <em>upload</em>
            handler still simply replies with "Hello Upload", but now
            by making use of the <em>response</em> object.
        </p>

        <p>
            If we start our application again (<em>node index.js</em>),
            this should work as expected.
        </p>

        <p>
            If you would like to prove that an expensive operation behind
            <em>/start</em> will no longer block requests for
            <em>/upload</em> from answering immediately, then modify your
            <em>requestHandlers.js</em> as follows:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> exec </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span class="str">"child_process"</span><span
                class="pun">).</span><span class="pln">exec</span><span class="pun">;</span><span
                class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; exec</span><span class="pun">(</span><span
                class="str">"find /"</span><span class="pun">,</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="pun">{</span><span class="pln"> timeout</span><span class="pun">:</span><span
                class="pln"> </span><span class="lit">10000</span><span class="pun">,</span><span
                class="pln"> maxBuffer</span><span class="pun">:</span><span class="pln"> </span><span
                class="lit">20000</span><span class="pun">*</span><span class="lit">1024</span><span
                class="pln"> </span><span class="pun">},</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">function</span><span class="pln"> </span><span class="pun">(</span><span
                class="pln">error</span><span class="pun">,</span><span class="pln"> stdout</span><span
                class="pun">,</span><span class="pln"> stderr</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; response</span><span
                class="pun">.</span><span class="pln">write</span><span class="pun">(</span><span
                class="pln">stdout</span><span class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; response</span><span
                class="pun">.</span><span class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="pun">});</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br></span><span
                class="kwd">function</span><span class="pln"> upload</span><span class="pun">(</span><span class="pln">response</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello Upload"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>exports</span><span class="pun">.</span><span class="pln">start </span><span
                class="pun">=</span><span class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            This will make HTTP requests to <a href="http://localhost:8888/start" rel="nofollow">http://localhost:8888/start</a>
            take at least 10 seconds, but requests to <a href="http://localhost:8888/upload" rel="nofollow">http://localhost:8888/upload</a>
            will be answered immediately, even if /start is still
            computing.
        </p>

        <a name="serving-something-useful"></a>

        <h3>Serving something useful</h3>

        <p>
            Until now, what we have done is all fine and dandy, but we
            haven't created any value for the customers of our
            award-winning website.
        </p>

        <p>
            Our server, router, and request handlers are in place, thus now
            we can begin to add content to our site which allows our users
            to interact and walk through the use case of choosing a file,
            uploading this file, and viewing the uploaded file in the
            browser. For the sake of simplicity we will assume that only
            image files are going to be uploaded and displayed through the
            application.
        </p>

        <p>
            Ok, let's take it step by step, but with most of the techniques
            and principles of JavaScript explained by now, let's at the
            same time accelerate a bit. This author likes to hear himself
            talking way too much anyways.
        </p>

        <p>
            Here, step by step means roughly two steps: We will first look
            at how to handle incoming POST requests (but not file uploads),
            and in a second step, we will make use of an external Node.js
            module for the file upload handling. I've chosen this approach
            for two reasons.
        </p>

        <p>
            First, handling basic POST requests is
            relatively simple with Node.js, but still teaches us enough to
            be worth exercising it.
            <br>
            Second, handling file uploads (i.e.,
            multipart POST requests) is <em>not</em> simple with Node.js,
            and therefore is beyond the scope of this tutorial, but using
            an external module is itself a lesson that makes sense to be
            included in a beginner's tutorial.
        </p>

        <a name="handling-post-requests"></a>

        <h4>Handling POST requests</h4>

        <p>
            Let's keep this banally simple: We will present a textarea that
            can be filled by the user and submitted to the server in a POST
            request. Upon receiving and handling this request, we will
            display the content of the textarea.
        </p>
        
        <p>
            The HTML for this textarea form needs to be served by our
            <em>/start</em> request handler, so let's add it right away, in
            file <em>requestHandlers.js</em>:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; </span><span class="kwd">var</span><span
                class="pln"> body </span><span class="pun">=</span><span class="pln"> </span><span class="str">'&lt;html&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;head&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;meta http-equiv="Content-Type" content="text/html; '</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'charset=UTF-8" /&gt;'</span><span class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/head&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;body&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;form action="/upload" method="post"&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;textarea name="text" rows="20" cols="60"&gt;&lt;/textarea&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;input type="submit" value="Submit text" /&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/form&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;/body&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/html&gt;'</span><span class="pun">;</span><span class="pln"><br><br>&nbsp; &nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/html"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="pln">body</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> upload</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"Hello Upload"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>exports</span><span class="pun">.</span><span class="pln">start </span><span
                class="pun">=</span><span class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            Now if this isn't going to win the Webby Awards, then I don't
            know what could. You should see this very simple form when
            requesting
            <a href="http://localhost:8888/start" rel="nofollow">http://localhost:8888/start</a>
            in your browser. If not, you probably didn't restart the
            application.
        </p>

        <p>
            I hear you: having view content right in the request handler is
            ugly. However, I decided to not include that extra level of
            abstraction (i.e., separating view and controller logic) in
            this tutorial, because I think that it doesn't teach us
            anything worth knowing in the context of JavaScript or Node.js.
        </p>

        <p>
            Let's rather use the remaining screen space for a more
            interesting problem, that is, handling the POST request
            that will hit our <em>/upload</em> request handler when the
            user submits this form.
        </p>

        <p>
            Now that we are becoming expert novices, we are no longer
            surprised by the fact that handling POST data is done in a
            non-blocking fashion, by using asynchronous callbacks.
        </p>

        <p>
            Which makes sense, because POST requests can potentially be
            very large - nothing stops the user from entering text that is
            multiple megabytes in size. Handling the whole bulk of data in
            one go would result in a blocking operation.
        </p>

        <p>
            To make the whole process non-blocking, Node.js serves our code
            the POST data in small chunks, callbacks that are called upon
            certain events. These events are <em>data</em> (an new chunk of
            POST data arrives) and <em>end</em> (all chunks have been
            received).
        </p>

        <p>
            We need to tell Node.js which functions to call back to when
            these events occur. This is done by adding <em>listeners</em>
            to the <em>request</em> object that is passed to our
            <em>onRequest</em> callback whenever an HTTP request is
            received.
        </p>

        <p>
            This basically looks like this:
        </p>
        <pre class="prettyprint lang-js"><span class="pln">request</span><span class="pun">.</span><span class="pln">addListener</span><span
                class="pun">(</span><span class="str">"data"</span><span class="pun">,</span><span
                class="pln"> </span><span class="kwd">function</span><span class="pun">(</span><span
                class="pln">chunk</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; </span><span class="com">// called when a new chunk of data was received</span><span
                class="pln"><br></span><span class="pun">});</span><span class="pln"><br><br>request</span><span
                class="pun">.</span><span class="pln">addListener</span><span class="pun">(</span><span class="str">"end"</span><span
                class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span
                class="pun">()</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; </span><span
                class="com">// called when all chunks of data have been received</span><span
                class="pln"><br></span><span class="pun">});</span></pre>

        <p>
            The question arises where to implement this logic. We currently
            can access the <em>request</em> object in our server only - we
            don't pass it on to the router and the request handlers, like
            we did with the <em>response</em> object.
        </p>

        <p>
            In my opinion, it's an HTTP servers job to give the application
            all the data from a requests it needs to do its job. Therefore,
            I suggest we handle the POST data processing right in the
            server and pass the final data on to the router and the request
            handlers, which then can decide what to do with it.
        </p>

        <p>
            Thus, the idea is to put the <em>data</em> and <em>end</em>
            event callbacks in the server, collecting all POST data chunks
            in the <em>data</em> callback, and calling the router upon
            receiving the <em>end</em> event, while passing the collected
            data chunks on to the router, which in turn passes it on to the
            request handlers.
        </p>

        <p>
            Here we go, starting with <em>server.js</em>:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> http </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span
                class="str">"http"</span><span class="pun">);</span><span class="pln"><br></span><span
                class="kwd">var</span><span class="pln"> url </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">"url"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">(</span><span class="pln">route</span><span
                class="pun">,</span><span class="pln"> handle</span><span class="pun">)</span><span class="pln"> </span><span
                class="pun">{</span><span class="pln"><br>&nbsp; </span><span class="kwd">function</span><span
                class="pln"> onRequest</span><span class="pun">(</span><span class="pln">request</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> postData </span><span class="pun">=</span><span
                class="pln"> </span><span class="str">""</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="kwd">var</span><span class="pln"> pathname </span><span class="pun">=</span><span class="pln"> url</span><span
                class="pun">.</span><span class="pln">parse</span><span class="pun">(</span><span
                class="pln">request</span><span class="pun">.</span><span class="pln">url</span><span
                class="pun">).</span><span class="pln">pathname</span><span class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">" received."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; &nbsp; request</span><span
                class="pun">.</span><span class="pln">setEncoding</span><span class="pun">(</span><span class="str">"utf8"</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; &nbsp; request</span><span
                class="pun">.</span><span class="pln">addListener</span><span class="pun">(</span><span class="str">"data"</span><span
                class="pun">,</span><span class="pln"> </span><span class="kwd">function</span><span
                class="pun">(</span><span class="pln">postDataChunk</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; &nbsp; &nbsp; postData </span><span class="pun">+=</span><span class="pln"> postDataChunk</span><span
                class="pun">;</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Received POST data chunk '"</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; postDataChunk </span><span
                class="pun">+</span><span class="pln"> </span><span class="str">"'."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="pun">});</span><span
                class="pln"><br><br>&nbsp; &nbsp; request</span><span class="pun">.</span><span
                class="pln">addListener</span><span class="pun">(</span><span class="str">"end"</span><span class="pun">,</span><span
                class="pln"> </span><span class="kwd">function</span><span class="pun">()</span><span
                class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; &nbsp; &nbsp; route</span><span class="pun">(</span><span
                class="pln">handle</span><span class="pun">,</span><span class="pln"> pathname</span><span
                class="pun">,</span><span class="pln"> response</span><span class="pun">,</span><span class="pln"> postData</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="pun">});</span><span
                class="pln"><br><br>&nbsp; </span><span class="pun">}</span><span class="pln"><br><br>&nbsp; http</span><span
                class="pun">.</span><span class="pln">createServer</span><span class="pun">(</span><span class="pln">onRequest</span><span
                class="pun">).</span><span class="pln">listen</span><span class="pun">(</span><span
                class="lit">8888</span><span class="pun">);</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Server has started."</span><span
                class="pun">);</span><span class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span></pre>

        <p>
            We basically did three things here: First, we defined that we
            expect the encoding of the received data to be UTF-8, we added
            an event listener for the "data" event which step by step
            fills our new <em>postData</em> variable whenever a new chunk
            of POST data arrives, and we moved the call to our router into
            the <em>end</em> event callback to make sure it's only called
            when all POST data is gathered. We also pass the POST data into
            the router, because we are going to need it in our request
            handlers.
        </p>

        <p>
            Adding the console logging on every chunk that is received
            probably is a bad idea for production code (megabytes of POST
            data, remember?), but makes sense to see what happens.
        </p>

        <p>
            I suggest playing around with this a bit. Put small
            amounts of text into the textarea as well as lots of text, and
            you will see that for the larger texts, the <em>data</em>
            callback is indeed called multiple times.
        </p>

        <p>
            Let's add even more awesome to our app. On the /upload page,
            we will display the received content. To make this possible, we
            need to pass the <em>postData</em> on to the request handlers,
            in <em>router.js</em>:
        </p>

        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> route</span><span
                class="pun">(</span><span class="pln">handle</span><span class="pun">,</span><span
                class="pln"> pathname</span><span class="pun">,</span><span class="pln"> response</span><span
                class="pun">,</span><span class="pln"> postData</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"About to route a request for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; </span><span class="kwd">if</span><span
                class="pln"> </span><span class="pun">(</span><span class="kwd">typeof</span><span
                class="pln"> handle</span><span class="pun">[</span><span class="pln">pathname</span><span
                class="pun">]</span><span class="pln"> </span><span class="pun">===</span><span
                class="pln"> </span><span class="str">'function'</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; handle</span><span
                class="pun">[</span><span class="pln">pathname</span><span class="pun">](</span><span class="pln">response</span><span
                class="pun">,</span><span class="pln"> postData</span><span class="pun">);</span><span class="pln"><br>&nbsp; </span><span
                class="pun">}</span><span class="pln"> </span><span class="kwd">else</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"No request handler found for "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> pathname</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">404</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"404 Not found"</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br>&nbsp; </span><span class="pun">}</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">route </span><span class="pun">=</span><span
                class="pln"> route</span><span class="pun">;</span></pre>

        <p>
            And in <em>requestHandlers.js</em>, we include the data in our
            response of the <em>upload</em> request handler:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">function</span><span class="pln"> start</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">,</span><span class="pln"> postData</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; </span><span class="kwd">var</span><span
                class="pln"> body </span><span class="pun">=</span><span class="pln"> </span><span class="str">'&lt;html&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;head&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;meta http-equiv="Content-Type" content="text/html; '</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'charset=UTF-8" /&gt;'</span><span class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/head&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;body&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;form action="/upload" method="post"&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;textarea name="text" rows="20" cols="60"&gt;&lt;/textarea&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;input type="submit" value="Submit text" /&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/form&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;/body&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/html&gt;'</span><span class="pun">;</span><span class="pln"><br><br>&nbsp; &nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/html"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="pln">body</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> upload</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">,</span><span class="pln"> postData</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"You've sent: "</span><span
                class="pln"> </span><span class="pun">+</span><span class="pln"> postData</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br>exports</span><span class="pun">.</span><span class="pln">start </span><span
                class="pun">=</span><span class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            That's it, we are now able to receive POST data and use it in
            our request handlers.
        </p>

        <p>
            One last thing for this topic: what we pass on to the router
            and the request handlers is the complete body of our POST
            request. We will probably want to consume the individual fields
            that make up the POST data, in this case, the value of the
            <em>text</em> field.
        </p>

        <p>
            We already read about the <em>querystring</em> module, which
            assists us with this:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> querystring </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span class="str">"querystring"</span><span
                class="pun">);</span><span class="pln"><br><br></span><span class="kwd">function</span><span
                class="pln"> start</span><span class="pun">(</span><span class="pln">response</span><span
                class="pun">,</span><span class="pln"> postData</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'start' was called."</span><span
                class="pun">);</span><span class="pln"><br><br>&nbsp; </span><span class="kwd">var</span><span
                class="pln"> body </span><span class="pun">=</span><span class="pln"> </span><span class="str">'&lt;html&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;head&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;meta http-equiv="Content-Type" content="text/html; '</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'charset=UTF-8" /&gt;'</span><span class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/head&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;body&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;form action="/upload" method="post"&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;textarea name="text" rows="20" cols="60"&gt;&lt;/textarea&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;input type="submit" value="Submit text" /&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/form&gt;'</span><span class="pun">+</span><span
                class="pln"><br>&nbsp; &nbsp; </span><span class="str">'&lt;/body&gt;'</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="str">'&lt;/html&gt;'</span><span class="pun">;</span><span class="pln"><br><br>&nbsp; &nbsp; response</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">"Content-Type"</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">"text/html"</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="pln">body</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; response</span><span class="pun">.</span><span
                class="pln">end</span><span class="pun">();</span><span class="pln"><br></span><span
                class="pun">}</span><span class="pln"><br><br></span><span class="kwd">function</span><span class="pln"> upload</span><span
                class="pun">(</span><span class="pln">response</span><span class="pun">,</span><span class="pln"> postData</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; console</span><span
                class="pun">.</span><span class="pln">log</span><span class="pun">(</span><span class="str">"Request handler 'upload' was called."</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">writeHead</span><span class="pun">(</span><span class="lit">200</span><span
                class="pun">,</span><span class="pln"> </span><span class="pun">{</span><span
                class="str">"Content-Type"</span><span class="pun">:</span><span class="pln"> </span><span class="str">"text/plain"</span><span
                class="pun">});</span><span class="pln"><br>&nbsp; response</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">"You've sent the text: "</span><span
                class="pun">+</span><span class="pln"><br>&nbsp; querystring</span><span class="pun">.</span><span
                class="pln">parse</span><span class="pun">(</span><span class="pln">postData</span><span
                class="pun">).</span><span class="pln">text</span><span class="pun">);</span><span class="pln"><br>&nbsp; response</span><span
                class="pun">.</span><span class="pln">end</span><span class="pun">();</span><span
                class="pln"><br></span><span class="pun">}</span><span class="pln"><br><br>exports</span><span
                class="pun">.</span><span class="pln">start </span><span class="pun">=</span><span
                class="pln"> start</span><span class="pun">;</span><span class="pln"><br>exports</span><span
                class="pun">.</span><span class="pln">upload </span><span class="pun">=</span><span
                class="pln"> upload</span><span class="pun">;</span></pre>

        <p>
            Well, for a beginner's tutorial, that's all there is to say
            about handling POST data.
        </p>

        <a name="handling-file-uploads"></a>

        <h4>Handling file uploads</h4>

        <p>
            Let's tackle our final use case. Our plan was to allow users to
            upload an image file, and display the uploaded image in the
            browser.
        </p>

        <p>
            Back in the 90's this would have qualified as a business model
            for an IPO, today it must suffice to teach us two things: how
            to install external Node.js libraries, and how to make use of
            them in our own code.
        </p>

        <p>
            The external module we are going to use is
            <em>node-formidable</em> by Felix Geisendörfer. It nicely
            abstracts away all the nasty details of parsing incoming file
            data. At the end of the day, handling incoming files is "only"
            about handling POST data - but the devil really <em>is</em> in
            the details here, and using a ready-made solution makes a lot
            of sense in this case.
        </p>

        <p>
            In order to make use of Felix' code, the according Node.js
            module needs to be installed. Node.js ships with its own
            package manager, dubbed <em>NPM</em>. It allows us to install
            external Node.js modules in a very convenient fashion. Given a
            working Node.js installation, it boils down to issuing
        </p>
        <pre class="prettyprint lang-bash"><span class="pln">npm install formidable</span></pre>

        <p>
            on our command line. If the following output ends with
        </p>
        <pre class="prettyprint lang-bash"><span class="pln">npm info build </span><span class="typ">Success</span><span
                class="pun">:</span><span class="pln"> formidable@1</span><span class="pun">.</span><span class="lit">0.9</span><span
                class="pln"><br>npm ok</span></pre>

        <p>
            then we are good to go.
        </p>

        <p>
            The <em>formidable</em> module is now available to our own
            code - all we need to do is requiring it just like one of the
            built-in modules we used earlier:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> formidable </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span class="str">"formidable"</span><span
                class="pun">);</span></pre>

        <p>
            The metaphor formidable uses is that of a form being submitted
            via HTTP POST, making it parseable in Node.js. All we need to
            do is create a new <em>IncomingForm</em>, which is an
            abstraction of this submitted form, and which can then be used
            to parse the <em>request</em> object of our HTTP server for the
            fields and files that were submitted through this form.
        </p>

        <p>
            The example code from the node-formidable project page shows
            how the different parts play together:
        </p>
        <pre class="prettyprint lang-js"><span class="kwd">var</span><span class="pln"> formidable </span><span
                class="pun">=</span><span class="pln"> require</span><span class="pun">(</span><span class="str">'formidable'</span><span
                class="pun">),</span><span class="pln"><br>&nbsp; &nbsp; http </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">'http'</span><span
                class="pun">),</span><span class="pln"><br>&nbsp; &nbsp; sys </span><span class="pun">=</span><span
                class="pln"> require</span><span class="pun">(</span><span class="str">'sys'</span><span
                class="pun">);</span><span class="pln"><br><br>http</span><span class="pun">.</span><span class="pln">createServer</span><span
                class="pun">(</span><span class="kwd">function</span><span class="pun">(</span><span
                class="pln">req</span><span class="pun">,</span><span class="pln"> res</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span
                class="pln"><br>&nbsp; </span><span class="kwd">if</span><span class="pln"> </span><span
                class="pun">(</span><span class="pln">req</span><span class="pun">.</span><span
                class="pln">url </span><span class="pun">==</span><span class="pln"> </span><span
                class="str">'/upload'</span><span class="pln"> </span><span class="pun">&amp;&amp;</span><span
                class="pln"> req</span><span class="pun">.</span><span class="pln">method</span><span
                class="pun">.</span><span class="pln">toLowerCase</span><span class="pun">()</span><span
                class="pln"> </span><span class="pun">==</span><span class="pln"> </span><span class="str">'post'</span><span
                class="pun">)</span><span class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; </span><span
                class="com">// parse a file upload</span><span class="pln"><br>&nbsp; &nbsp; </span><span class="kwd">var</span><span
                class="pln"> form </span><span class="pun">=</span><span class="pln"> </span><span
                class="kwd">new</span><span class="pln"> formidable</span><span class="pun">.</span><span class="typ">IncomingForm</span><span
                class="pun">();</span><span class="pln"><br>&nbsp; &nbsp; form</span><span class="pun">.</span><span
                class="pln">parse</span><span class="pun">(</span><span class="pln">req</span><span class="pun">,</span><span
                class="pln"> </span><span class="kwd">function</span><span class="pun">(</span><span
                class="pln">err</span><span class="pun">,</span><span class="pln"> fields</span><span
                class="pun">,</span><span class="pln"> files</span><span class="pun">)</span><span
                class="pln"> </span><span class="pun">{</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; res</span><span
                class="pun">.</span><span class="pln">writeHead</span><span class="pun">(</span><span
                class="lit">200</span><span class="pun">,</span><span class="pln"> </span><span
                class="pun">{</span><span class="str">'content-type'</span><span class="pun">:</span><span
                class="pln"> </span><span class="str">'text/plain'</span><span class="pun">});</span><span
                class="pln"><br>&nbsp; &nbsp; &nbsp; res</span><span class="pun">.</span><span
                class="pln">write</span><span class="pun">(</span><span class="str">'received upload:\n\n'</span><span
                class="pun">);</span><span class="pln"><br>&nbsp; &nbsp; &nbsp; res</span><span
                class="pun">.</span><span class="pln">end</span><span class="pun">(</span><span
                class="pln">sys</span><span class="pun">.</span><span class="pln">inspect</span><span
                class="pun">({</span><span class="pln">fields</span><span class="pun">:</span><span
                class="pln"> fields</span><span class="pun">,</span><span