Author: buildbot
Date: Mon Feb 12 12:21:02 2018
New Revision: 1025260
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/assets.html
websites/production/tapestry/content/cache/main.pageCache
Modified: websites/production/tapestry/content/assets.html
==============================================================================
--- websites/production/tapestry/content/assets.html (original)
+++ websites/production/tapestry/content/assets.html Mon Feb 12 12:21:02 2018
@@ -163,7 +163,7 @@ private Asset icon;
@Path("${skin.root}/style.css")
private Asset style;
</pre>
-</div></div><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The use of the <code>${...</code>}
syntax here is a <em>symbol expansion</em> (because it occurs in an annotation
in Java code), rather than a <em>template expansion</em> (which occurs only in
Tapestry template files).</p></div></div><p>An override of the skin.root symbol
would affect all references to the named asset.</p><h3
id="Assets-LocalizationofAssets">Localization of Assets</h3><p>Main Article: <a
href="assets.html">Assets</a></p><p>Assets are localized; Tapestry will search
for a variation of the file appropriate to the effective locale for the
request. In the previous example, a German user of the application may see a
file named <code>edit_de.png</code> (if such a file exists).</p><h3
id="Assets-NewAssetDomains">New Asset Domains</h3><p>I
f you wish to create new domains for assets, for example to allow assets to be
stored on the file system or in a database, you may define a new <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/AssetFactory.html";>AssetFactory</a>
and contribute it to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/AssetSource.html";>AssetSource</a>
service configuration.</p><h3
id="Assets-AssetFingerprinting(Tapestry5.3andearlier)">Asset Fingerprinting
(Tapestry 5.3 and earlier)</h3><p>Tapestry creates a new URL for assets
(whether context or classpath). The URL is of the form
/assets/<strong>version</strong>/<strong>folder</strong>/<strong>path</strong>.</p><ul><li><strong>version</strong>:
Application version number, defined by the
<code>tapestry.application-version</code> symbol in your application module
(normally AppModule.java). The default is a random hex number.</li><li><strong>
folder</strong>: Identifies the library containing the asset, or "ctx" for a
context asset, or "stack" (used when combining multiple JavaScript files into a
single virtual asset).</li><li><strong>path</strong>: The path below the root
package of the library to the specific asset file.</li></ul><h3
id="Assets-AssetFingerprinting(Tapestry5.4andlater)">Asset
Fingerprinting<span> (Tapestry 5.4 and later)</span></h3><p>Tapestry 5.4
changes how Asset URLs are constructed. The version number is now
a <em>content fingerprint</em>, a hash of the actual content of the
asset.</p><p>Assets get a far-future expires header. It is no longer necessary
or desirable to change the application version number.</p><p>During development
or production, if an asset is changed in any way, it will have a new content
fingerprint and will appear, to the browser, to be an entirely new immutable
resource.</p><h3 id="Assets-CSSLinkRewriting">CSS Link Rewriting</h3><p>It is
frequently the case that CSS fi
les will include links to other files, such as background images, using
the <code>url</code>() value syntax. Under 5.4, the URL for the CSS file
and the targeted file would be broken, due to the inclusions of the CSS file's
content hash fingerprint. To fix this, Tapestry parses CSS files, locates
the <code>url()</code> directives, and rewrites the URLs to be absolute
(including the targeted file's content hash fingerprint).</p><h3
id="Assets-PerformanceNotes">Performance Notes</h3><p>Assets are expected to be
entirely static (not changing while the application is deployed). This allows
Tapestry to perform some important performance optimizations.</p><p>Tapestry
GZIP compresses the content of all assets – if the asset is compressible,
the client supports it, and you don't <a href="assets.html">explicitly disable
it</a>.</p><p><span>Further, the asset will get a </span><em>far future expires
header</em><span>, which will encourage the client browser to cache the asset
.</span></p><p>You should have an explicit application version number for any
production application. Client browsers will aggressively cache downloaded
assets; they will usually not even send a request to see if the asset has
changed once the asset is downloaded the first time. Because of this it is
<em>very important</em> that each new deployment of your application has a new
<a href="assets.html">version number</a>, to force existing clients to
re-download all assets.</p><h3 id="Assets-AssetSecurity">Asset
Security</h3><div class="confluence-information-macro
confluence-information-macro-warning"><span class="aui-icon aui-icon-small
aui-iconfont-error confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This applies to how Tapestry 5.3
and earlier manage classpath assets; Tapestry 5.4 introduces another system
which doesn't have this issue.</p></div></div><p>Because Tapestry directly
exposes files on the classpath to the clients, some thoug
ht has gone into ensuring that malicious clients are not able to download
assets that should not be visible to them.</p><p>First off all, there's a
package limitation: classpath assets are only visible if there's a <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/LibraryMapping.html";>LibraryMapping</a>
for them, and the library mapping substitutes for the initial folders on the
classpath. Since the most secure assets, things like
<code>hibernate.cfg.xml</code> are located in the unnamed package, they are
always off limits.</p><p>But what about other files on the classpath? Imagine
this scenario:</p><ul><li>Your Login page exposes a classpath asset,
<code>icon.png</code>.</li><li><p>A malicious client copies the URL,
<code>/assets/1.0.0/app/pages/icon.png (</code><span>which would indicate that
the Login page is actually inside a library, which is unlikely. More likely,
icon.png is a context asset and the malicious user guessed
the path for Login.class by looking at the Tapestry source
code.) </span><span>and changes the file name to
</span><code>Login.class</code><span>.</span></p></li><li><p>The client
decompiles the class file and spots your secret emergency password: goodbye
security! (<span>Never create such back doors, of
course!)</span></p></li></ul><p>Fortunately, this can't happen. Files with
extension ".class" are secured; they must be accompanied in the URL with a
query parameter that is the MD5 hash of the file's contents. If the query
parameter is absent, or doesn't match the actual file's content, the request is
rejected.</p><p>When your code exposes an Asset that is secured, Tapestry
generates a URL that automatically includes MD5 hash query parameter. The
malicious user is locked out of access to the files. (The only way they could
generate the MD5 hash is if<span> they somehow already have the files, in which
case they don't need to download them again anyway.)</span></p><p>By default
, Tapestry secures file extensions ".class', ".tml" and ".properties". The
list can be extended by contributing to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ResourceDigestGenerator.html";>ResourceDigestGenerator</a>
service:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent
pdl">
+</div></div><div class="confluence-information-macro
confluence-information-macro-note"><span class="aui-icon aui-icon-small
aui-iconfont-warning confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>The use of the <code>${...</code>}
syntax here is a <em>symbol expansion</em> (because it occurs in an annotation
in Java code), rather than a <em>template expansion</em> (which occurs only in
Tapestry template files).</p></div></div><p>An override of the skin.root symbol
would affect all references to the named asset.</p><h3
id="Assets-LocalizationofAssets">Localization of Assets</h3><p>Main Article: <a
href="assets.html">Assets</a></p><p>Assets are localized; Tapestry will search
for a variation of the file appropriate to the effective locale for the
request. In the previous example, a German user of the application may see a
file named <code>edit_de.png</code> (if such a file exists).</p><h3
id="Assets-NewAssetDomains">New Asset Domains</h3><p>I
f you wish to create new domains for assets, for example to allow assets to be
stored on the file system or in a database, you may define a new <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/AssetFactory.html";>AssetFactory</a>
and contribute it to the <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/AssetSource.html";>AssetSource</a>
service configuration.</p><h3
id="Assets-AssetFingerprinting(Tapestry5.3andearlier)">Asset Fingerprinting
(Tapestry 5.3 and earlier)</h3><p>Tapestry creates a new URL for assets
(whether context or classpath). The URL is of the form
/assets/<strong>version</strong>/<strong>folder</strong>/<strong>path</strong>.</p><ul><li><strong>version</strong>:
Application version number, defined by the
<code>tapestry.application-version</code> symbol in your application module
(normally AppModule.java). The default is a random hex number.</li><li><strong>
folder</strong>: Identifies the library containing the asset, or "ctx" for a
context asset, or "stack" (used when combining multiple JavaScript files into a
single virtual asset).</li><li><strong>path</strong>: The path below the root
package of the library to the specific asset file.</li></ul><h3
id="Assets-AssetFingerprinting(Tapestry5.4andlater)">Asset
Fingerprinting<span> (Tapestry 5.4 and later)</span></h3><p>Tapestry 5.4
changes how Asset URLs are constructed. The version number is now
a <em>content fingerprint</em>, a hash of the actual content of the
asset.</p><p>Assets get a far-future expires header. It is no longer necessary
or desirable to change the application version number.</p><p>During development
or production, if an asset is changed in any way, it will have a new content
fingerprint and will appear, to the browser, to be an entirely new immutable
resource.</p><h3 id="Assets-CSSLinkRewriting">CSS Link Rewriting</h3><p>It is
frequently the case that CSS fi
les will include links to other files, such as background images, using
the <code>url</code>() value syntax. Under 5.4, the URL for the CSS file
and the targeted file would be broken, due to the inclusions of the CSS file's
content hash fingerprint. To fix this, Tapestry parses CSS files, locates
the <code>url()</code> directives, and rewrites the URLs to be absolute
(including the targeted file's content hash fingerprint).</p><h3
id="Assets-PerformanceNotes">Performance Notes</h3><p>Assets are expected to be
entirely static (not changing while the application is deployed). This allows
Tapestry to perform some important performance optimizations.</p><p>Tapestry
GZIP compresses the content of all assets – if the asset is compressible,
the client supports it, and you don't <a href="assets.html">explicitly disable
it</a>.</p><p><span>Further, the asset will get a </span><em>far future expires
header</em><span>, which will encourage the client browser to cache the asset
.</span></p><p>For Talestry 5.3 and earlier, you should have an explicit
application version number for any production application. Client browsers will
aggressively cache downloaded assets; they will usually not even send a request
to see if the asset has changed once the asset is downloaded the first time.
Because of this it is <em>very important</em> that each new deployment of your
application has a new <a href="assets.html">version number</a>, to force
existing clients to re-download all assets.</p><h3
id="Assets-AssetSecurity">Asset Security</h3><div
class="confluence-information-macro confluence-information-macro-warning"><span
class="aui-icon aui-icon-small aui-iconfont-error
confluence-information-macro-icon"></span><div
class="confluence-information-macro-body"><p>This applies to how Tapestry 5.3
and earlier manage classpath assets; Tapestry 5.4 introduces another system
which doesn't have this issue.</p></div></div><p>Because Tapestry directly
exposes files on the classp
ath to the clients, some thought has gone into ensuring that malicious clients
are not able to download assets that should not be visible to them.</p><p>First
off all, there's a package limitation: classpath assets are only visible if
there's a <a class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/LibraryMapping.html";>LibraryMapping</a>
for them, and the library mapping substitutes for the initial folders on the
classpath. Since the most secure assets, things like
<code>hibernate.cfg.xml</code> are located in the unnamed package, they are
always off limits.</p><p>But what about other files on the classpath? Imagine
this scenario:</p><ul><li>Your Login page exposes a classpath asset,
<code>icon.png</code>.</li><li><p>A malicious client copies the URL,
<code>/assets/1.0.0/app/pages/icon.png (</code><span>which would indicate that
the Login page is actually inside a library, which is unlikely. More likely,
icon.png is a context asset a
nd the malicious user guessed the path for Login.class by looking at the
Tapestry source code.) </span><span>and changes the file name to
</span><code>Login.class</code><span>.</span></p></li><li><p>The client
decompiles the class file and spots your secret emergency password: goodbye
security! (<span>Never create such back doors, of
course!)</span></p></li></ul><p>Fortunately, this can't happen. Files with
extension ".class" are secured; they must be accompanied in the URL with a
query parameter that is the MD5 hash of the file's contents. If the query
parameter is absent, or doesn't match the actual file's content, the request is
rejected.</p><p>When your code exposes an Asset that is secured, Tapestry
generates a URL that automatically includes MD5 hash query parameter. The
malicious user is locked out of access to the files. (The only way they could
generate the MD5 hash is if<span> they somehow already have the files, in which
case they don't need to download them again an
yway.)</span></p><p>By default, Tapestry secures file extensions ".class',
".tml" and ".properties". The list can be extended by contributing to the <a
class="external-link"
href="http://tapestry.apache.org/current/apidocs/org/apache/tapestry5/services/ResourceDigestGenerator.html";>ResourceDigestGenerator</a>
service:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeHeader panelHeader pdl" style="border-bottom-width:
1px;"><b>AppModule.java (partial)</b></div><div class="codeContent panelContent
pdl">
<pre class="brush: java; gutter: false; theme: Default"
style="font-size:12px;">public static void
contributeResourceDigestGenerator(Configuration<String> configuration)
{
configuration.add("xyz");
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
