agoo 2.15.10 → 2.15.12

data/misc/glue-diagram.svg

@@ -0,0 +1,3 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xl="http://www.w3.org/1999/xlink" version="1.1" viewBox="111 253 1309 657" width="1309pt" height="657pt" xmlns:dc="http://purl.org/dc/elements/1.1/"><metadata> Produced by OmniGraffle 6.6.2 <dc:date>2018-04-05 21:55:13 +0000</dc:date></metadata><defs><font-face font-family="Helvetica Neue" font-size="16" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.99585" descent="-212.99744" font-weight="500"><font-face-src><font-face-name name="HelveticaNeue"/></font-face-src></font-face><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="FilledArrow_Marker" viewBox="-1 -3 7 6" markerWidth="7" markerHeight="6" color="black"><g><path d="M 4.8 0 L 0 -1.8 L 0 1.8 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/></g></marker><marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="FilledArrow_Marker_2" viewBox="-6 -3 7 6" markerWidth="7" markerHeight="6" color="black"><g><path d="M -4.8 0 L 0 1.8 L 0 -1.8 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/></g></marker></defs><g stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1"><title>Canvas 1</title><g><title>Layer 1</title><rect x="453.5433" y="255.11811" width="113.385826" height="56.692913" fill="#6f6"/><rect x="453.5433" y="255.11811" width="113.385826" height="56.692913" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(458.5433 274.24057)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="black" x="13.764913" y="15" textLength="75.856">JavaScript</tspan></text><path d="M 497.88976 566.92913 L 635.9685 566.92913 C 644.80506 566.92913 651.9685 574.09257 651.9685 582.92913 L 651.9685 607.62204 C 651.9685 616.4586 644.80506 623.62204 635.9685 623.62204 L 497.88976 623.62204 C 489.0532 623.62204 481.88976 616.4586 481.88976 607.62204 L 481.88976 582.92913 C 481.88976 574.09257 489.0532 566.92913 497.88976 566.92913 Z" fill="green"/><path d="M 497.88976 566.92913 L 635.9685 566.92913 C 644.80506 566.92913 651.9685 574.09257 651.9685 582.92913 L 651.9685 607.62204 C 651.9685 616.4586 644.80506 623.62204 635.9685 623.62204 L 497.88976 623.62204 C 489.0532 623.62204 481.88976 616.4586 481.88976 607.62204 L 481.88976 582.92913 C 481.88976 574.09257 489.0532 566.92913 497.88976 566.92913 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(486.88976 586.0516)" fill="white"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="white" x="11.1273696" y="15" textLength="137.824">Rack::Push.publish</tspan></text><ellipse cx="1020.47243" cy="297.6378" rx="56.693004" ry="42.519753" fill="#6cf"/><ellipse cx="1020.47243" cy="297.6378" rx="56.693004" ry="42.519753" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(980.1181 279.1898)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="11.1783304" y="15" textLength="37.024">Exter</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="48.49033" y="15" textLength="25.488">nal </tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".20233044" y="33.447998" textLength="80.304">Application</tspan></text><ellipse cx="1190.5512" cy="297.6378" rx="56.693004" ry="42.519753" fill="#6cf"/><ellipse cx="1190.5512" cy="297.6378" rx="56.693004" ry="42.519753" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(1150.19684 279.1898)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="11.1783304" y="15" textLength="37.024">Exter</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="48.49033" y="15" textLength="25.488">nal </tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".20233044" y="33.447998" textLength="80.304">Application</tspan></text><ellipse cx="1360.6299" cy="297.6378" rx="56.693004" ry="42.519753" fill="#6cf"/><ellipse cx="1360.6299" cy="297.6378" rx="56.693004" ry="42.519753" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(1320.2756 279.1898)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="11.1783304" y="15" textLength="37.024">Exter</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="48.49033" y="15" textLength="25.488">nal </tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".20233044" y="33.447998" textLength="80.304">Application</tspan></text><path d="M 737.00787 255.11811 L 793.7008 255.11811 L 822.04724 283.46457 L 765.35433 340.15748 L 708.6614 283.46457 Z" fill="red"/><path d="M 737.00787 255.11811 L 793.7008 255.11811 L 822.04724 283.46457 L 765.35433 340.15748 L 708.6614 283.46457 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(713.6614 275.65789)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="black" x="18.356913" y="15" textLength="66.672">Publisher</tspan></text><path d="M 894.74015 566.92913 L 1032.8189 566.92913 C 1041.65545 566.92913 1048.8189 574.09257 1048.8189 582.92913 L 1048.8189 607.62204 C 1048.8189 616.4586 1041.65545 623.62204 1032.8189 623.62204 L 894.74015 623.62204 C 885.9036 623.62204 878.74015 616.4586 878.74015 607.62204 L 878.74015 582.92913 C 878.74015 574.09257 885.9036 566.92913 894.74015 566.92913 Z" fill="#0080ff"/><path d="M 894.74015 566.92913 L 1032.8189 566.92913 C 1041.65545 566.92913 1048.8189 574.09257 1048.8189 582.92913 L 1048.8189 607.62204 C 1048.8189 616.4586 1041.65545 623.62204 1032.8189 623.62204 L 894.74015 623.62204 C 885.9036 623.62204 878.74015 616.4586 878.74015 607.62204 L 878.74015 582.92913 C 878.74015 574.09257 885.9036 566.92913 894.74015 566.92913 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(883.74015 586.0516)" fill="white"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="white" x="28.77537" y="15" textLength="37.024">Exter</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="white" x="66.08737" y="15" textLength="65.216">n.publish</tspan></text><path d="M 481.88976 425.19685 L 538.58267 425.19685 L 566.92913 453.5433 L 510.23622 510.23622 L 453.5433 453.5433 Z" fill="red"/><path d="M 481.88976 425.19685 L 538.58267 425.19685 L 566.92913 453.5433 L 510.23622 510.23622 L 453.5433 453.5433 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(458.5433 436.51263)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="17.612913" y="15" textLength="72.608">Extended </tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="23.692913" y="33.447998" textLength="56">Handler</tspan></text><line x1="510.23622" y1="425.19685" x2="510.23622" y2="324.71102" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="493.23622" y="340.08764" width="34" height="47" fill="white"/><text transform="translate(498.23622 345.13964)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="black" x=".448" y="15" textLength="23.104">foo</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="black" x=".296" y="33.447998" textLength="23.408">bar</tspan></text><rect x="283.46457" y="255.11811" width="113.385826" height="56.692913" fill="#6f6"/><rect x="283.46457" y="255.11811" width="113.385826" height="56.692913" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(288.46457 274.24057)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="13.764913" y="15" textLength="75.856">JavaScript</tspan></text><path d="M 311.81102 425.19685 L 368.50393 425.19685 L 396.8504 453.5433 L 340.15748 510.23622 L 283.46457 453.5433 Z" fill="red"/><path d="M 311.81102 425.19685 L 368.50393 425.19685 L 396.8504 453.5433 L 340.15748 510.23622 L 283.46457 453.5433 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(288.46457 436.51263)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="17.612913" y="15" textLength="72.608">Extended </tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="23.692913" y="33.447998" textLength="56">Handler</tspan></text><line x1="340.15748" y1="425.19685" x2="340.15748" y2="324.71102" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="323.15748" y="348.58763" width="34" height="30" fill="white"/><text transform="translate(328.15748 354.36364)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><rect x="113.385826" y="255.11811" width="113.385826" height="56.692913" fill="#6f6"/><rect x="113.385826" y="255.11811" width="113.385826" height="56.692913" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(118.385826 274.24057)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="13.764913" y="15" textLength="75.856">JavaScript</tspan></text><path d="M 141.73228 425.19685 L 198.4252 425.19685 L 226.77165 453.5433 L 170.07874 510.23622 L 113.385826 453.5433 Z" fill="red"/><path d="M 141.73228 425.19685 L 198.4252 425.19685 L 226.77165 453.5433 L 170.07874 510.23622 L 113.385826 453.5433 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(118.385826 436.51263)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="17.612913" y="15" textLength="72.608">Extended </tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="23.692913" y="33.447998" textLength="56">Handler</tspan></text><line x1="170.07874" y1="425.19685" x2="170.07874" y2="324.71102" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="153.07874" y="348.58763" width="34" height="30" fill="white"/><text transform="translate(158.07874 354.36364)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".296" y="15" textLength="23.408">bar</tspan></text><path d="M 481.88976 595.2756 L 425.19685 595.2756 L 425.19685 396.8504" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="408.19685" y="498.34777" width="34" height="30" fill="white"/><text transform="translate(413.19685 504.12377)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><line x1="353.05747" y1="396.86174" x2="497.33622" y2="396.98865" marker-end="url(#FilledArrow_Marker)" marker-start="url(#FilledArrow_Marker_2)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><path d="M 566.92913 822.04724 L 623.62204 822.04724 L 651.9685 850.3937 L 595.2756 907.0866 L 538.58267 850.3937 Z" fill="red"/><path d="M 566.92913 822.04724 L 623.62204 822.04724 L 651.9685 850.3937 L 595.2756 907.0866 L 538.58267 850.3937 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(543.58267 842.587)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="23.244913" y="15" textLength="56.896">Listener</tspan></text><path d="M 696.31496 680.31496 L 834.3937 680.31496 C 843.23025 680.31496 850.3937 687.4784 850.3937 696.31496 L 850.3937 721.00787 C 850.3937 729.84443 843.23025 737.00787 834.3937 737.00787 L 696.31496 737.00787 C 687.4784 737.00787 680.31496 729.84443 680.31496 721.00787 L 680.31496 696.31496 C 680.31496 687.4784 687.4784 680.31496 696.31496 680.31496 Z" fill="maroon"/><path d="M 696.31496 680.31496 L 834.3937 680.31496 C 843.23025 680.31496 850.3937 687.4784 850.3937 696.31496 L 850.3937 721.00787 C 850.3937 729.84443 843.23025 737.00787 834.3937 737.00787 L 696.31496 737.00787 C 687.4784 737.00787 680.31496 729.84443 680.31496 721.00787 L 680.31496 696.31496 C 680.31496 687.4784 687.4784 680.31496 696.31496 680.31496 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(685.31496 699.4374)" fill="white"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="white" x="32.47137" y="15" textLength="95.136">Local.publish</tspan></text><path d="M 737.00787 822.04724 L 793.7008 822.04724 L 822.04724 850.3937 L 765.35433 907.0866 L 708.6614 850.3937 Z" fill="red"/><path d="M 737.00787 822.04724 L 793.7008 822.04724 L 822.04724 850.3937 L 765.35433 907.0866 L 708.6614 850.3937 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(713.6614 842.587)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="23.244913" y="15" textLength="56.896">Listener</tspan></text><path d="M 907.0866 822.04724 L 963.7795 822.04724 L 992.126 850.3937 L 935.43307 907.0866 L 878.74015 850.3937 Z" fill="red"/><path d="M 907.0866 822.04724 L 963.7795 822.04724 L 992.126 850.3937 L 935.43307 907.0866 L 878.74015 850.3937 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(883.74015 842.587)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x="23.244913" y="15" textLength="56.896">Listener</tspan></text><path d="M 680.31496 708.6614 L 595.2756 708.6614 L 595.2756 809.14724" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="615.55684" y="693.6614" width="34" height="30" fill="white"/><text transform="translate(620.55684 699.4374)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><line x1="765.35433" y1="737.00787" x2="765.35433" y2="809.14724" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="748.35433" y="748.92876" width="34" height="47" fill="white"/><text transform="translate(753.35433 753.98076)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".296" y="33.447998" textLength="23.408">bar</tspan></text><path d="M 850.3937 708.6614 L 935.43307 708.6614 L 935.43307 809.14724" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="881.1518" y="693.6614" width="34" height="30" fill="white"/><text transform="translate(886.1518 699.4374)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".296" y="15" textLength="23.408">bar</tspan></text><path d="M 1039.30975 568.3005 L 1360.6299 453.5433 L 1360.6299 353.0575" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="1147.7254" y="508.5092" width="34" height="30" fill="white"/><text transform="translate(1152.7254 514.2852)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="black" x=".296" y="15" textLength="23.408">bar</tspan></text><path d="M 1009.13385 566.92913 L 1190.5512 453.5433 L 1190.5512 353.0575" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="1056.76955" y="503.03182" width="34" height="47" fill="white"/><text transform="translate(1061.76955 508.08382)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".296" y="33.447998" textLength="23.408">bar</tspan></text><path d="M 975.1181 566.92913 L 1020.47243 453.5433 L 1020.47243 353.0575" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="977.94566" y="502.36023" width="34" height="30" fill="white"/><text transform="translate(982.94566 508.13623)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><path d="M 696.31496 425.19685 L 834.3937 425.19685 C 843.23025 425.19685 850.3937 432.3603 850.3937 441.19685 L 850.3937 465.88976 C 850.3937 474.72632 843.23025 481.88976 834.3937 481.88976 L 696.31496 481.88976 C 687.4784 481.88976 680.31496 474.72632 680.31496 465.88976 L 680.31496 441.19685 C 680.31496 432.3603 687.4784 425.19685 696.31496 425.19685 Z" fill="#8000ff"/><path d="M 696.31496 425.19685 L 834.3937 425.19685 C 843.23025 425.19685 850.3937 432.3603 850.3937 441.19685 L 850.3937 465.88976 C 850.3937 474.72632 843.23025 481.88976 834.3937 481.88976 L 696.31496 481.88976 C 687.4784 481.88976 680.31496 474.72632 680.31496 465.88976 L 680.31496 441.19685 C 680.31496 432.3603 687.4784 425.19685 696.31496 425.19685 Z" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/><text transform="translate(685.31496 444.3193)" fill="white"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" fill="white" x="35.28737" y="15" textLength="89.504">Glue.publish</tspan></text><line x1="765.35433" y1="340.15748" x2="765.35433" y2="412.29685" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="748.35433" y="351.29603" width="34" height="30" fill="white"/><text transform="translate(753.35433 357.07203)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><line x1="765.35433" y1="481.88976" x2="765.35433" y2="667.41496" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="748.35433" y="527.8797" width="34" height="30" fill="white"/><text transform="translate(753.35433 533.6557)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><path d="M 776.6929 481.88976 L 822.04724 595.2756 L 865.84015 595.2756" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="784.32935" y="528.48087" width="34" height="30" fill="white"/><text transform="translate(789.32935 534.25687)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text><path d="M 754.01574 481.88976 L 708.6614 595.2756 L 664.8685 595.2756" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/><rect x="712.3793" y="528.48087" width="34" height="30" fill="white"/><text transform="translate(717.3793 534.25687)" fill="black"><tspan font-family="Helvetica Neue" font-size="16" font-weight="500" x=".448" y="15" textLength="23.104">foo</tspan></text></g></g></svg>

data/misc/glue.md

@@ -0,0 +1,25 @@
+
+# Glue
+
+The publish and subscribe model can be used in several different ways. It can
+be used as a process integration tool where a Ruby object publishes to
+external application using something Redis or NATS. It can also be used as
+means for Ruby object to exchange data using subject or channel based
+addressing. It can also be used to push data to external listeners over a
+WebSocket or SSE connection.
+
+If there is a desire to merge all three into one API then a glue component can
+be introduced that distributes messages across all three (or more)
+systems. The glue component could also be used to bridge publish servers so
+that a message received on the Extern.publish (represents a server) could then
+be bridge to both the Local.publish and Rack::Push.publish servers.
+
+The use of a glue component allows each of the three servers to be written
+completely independently. It also allows different implemenations of each to
+be used if the developer wish to change any of the servers.
+
+The diagram shows publishing from a Ruby object to a listener through a
+server. In each case the reverse is also possible except for an SSE
+connection.
+
+![](glue-diagram.svg)

data/misc/optimize.md

@@ -0,0 +1,100 @@
+# Optimizing Agoo
+
+Right out of the box Agoo is fast but to take full advantage of all Agoo's
+features some configuration changes can be made. Those changes allow Agoo to
+circumvent the default Rails and Rack behavior.
+
+### Rack and Rails
+
+Both Rack and Rails with Rack expect to handle all HTTP requests. The `call`
+method is expected to handle serving static assets as well as Ruby
+processing. Usually a stack of middleware is used for processing.
+
+#### Static Assets
+
+The Rack approach is fine except that using a middleware stack to handle
+requests for static assets is expensive. Fortunately Rack expects static
+assests to be in the `./public` directory by convention. Rails deviates a bit
+and sets up an alias for a set of directories so that a request to `/assets`
+gets resolved to a lookup in one of several directories. The first match is
+then returned. Its a nice feature. The `/assets` directory group is described
+in the `Rails.configuration.assets.paths` variable.
+
+#### De-multiplexing Handlers
+
+Rack does the de-multiplexing of HTTP requests in Ruby. That means a request
+on `/hello` and one on `/goodbye` hit a Ruby call to decide that Ruby handler
+should take care of the request. Many other web servers handle that type of
+de-multiplexing before passing control to the handlers.
+
+### Agoo to the Rescue
+
+Agoo has some options to work around the Rack and Rails defaults while
+preserving the overall behavior.
+
+#### Static Assets
+
+The Ruby middleware stack isn't really needed to serve static assets. By
+default when `rackup` is used with Rails requests on `/assets` is resolved
+into a check of the value of `Rails.configuration.assets.paths` at start up
+just as Rails does. The difference is that request is handled completely by
+Agoo and never touches Ruby code. This results in several orders of magnitude
+better performance.
+
+For straight Rack, when `rackup` is called or when ever the
+`Rack::Handler::Agoo` handler is used the `./public` directory is checked
+before calling the Ruby handle `call` method. This is controlled by the `rmux`
+option which default to true. Calling `rackup` with an argument of `-O
+root_first=false` turns that option off.
+
+To set up path groups like the `/assets` group that Rails uses a call to
+`Agoo::Server.path_group` is made.
+
+#### De-multiplexing Handlers
+
+In any non-trivial application multiple Ruby classes are used to process
+requests. Maybe `/users` is handle by one class and `/articles` is handled by
+another. In Rails those classes are buried deep within Rails. You can still
+bypass Rails and Rack middleware if you want to for ancillary handlers. If
+building an application directly using the Rack spec and want take a more
+direct approach to invoking handlers then the Agoo de-multiplexing options
+make the application request handling much simpler.
+
+Setting up handlers for specific paths uses the `Agoo::Server.handle`
+method. When a request arrives each handler path is checked in the order they
+were registered. As and example, if these two calls were made.
+
+```ruby
+Agoo::Server.handle(nil, '/one', FirstHandler)
+Agoo::Server.handle(nil, '/**', CatchAll)
+```
+
+If a request arrive on `/one` the `FirstHandler` will be called. If on `/two`
+the `CatchAll` handler will be called.
+
+The handlers paths can be set up using `rackup` as well. Since `rackup`
+already registers `/**` to the Rack handler it is the `CatchAll` in the above
+example. To register handlers before that the `-O /one=FirstHandle` option is
+added to the `rackup` arguments.
+
+### Putting it all Together
+
+Using both static asset configurations and de-multiplexing will give the best
+performance. Couple that with Agoo's cluster option on a multithreaded machine
+give an even bigger win.
+
+### Examples
+
+For a `rackup` setup with static assets in `./assets` and a handler for
+`/help` that uses the `HelpMe` class.
+
+`rackup -d ./assets -O /help=HelpMe`
+
+For a Ruby startup using `ruby app.rb` add these to the app to use `./public`
+for static assets but add a group that handles assets at `./assets` and also
+`./public/assets`.
+
+```ruby
+Agoo::Server.init(9292, `./public`, root_first: true)
+Agoo::Server.path_group('./assets`, [`./assets`, `./public/assets'])
+```