		# @podium/client

		Client for fetching podium component fragments over HTTP.

		[![Build Status](https://travis-ci.org/podium-lib/client.svg?branch=master)](https://travis-ci.org/podium-lib/client) [![Greenkeeper badge](https://badges.greenkeeper.io/podium-lib/client.svg)](https://greenkeeper.io/)
		[![Known Vulnerabilities](https://snyk.io/test/github/podium-lib/client/badge.svg)](https://snyk.io/test/github/podium-lib/client)

		Client for fetching podium component fragments over HTTP.
		This module is intended for internal use in Podium and is not a module an end
		user would use directly. End users will typically interact with this module
		through higher level modules such as the [@podium/layout].

		@@ -66,3 +70,4 @@ ## Installation

		The client instance is iterable and holds a reference to each registered resource.
		The client instance is iterable and holds a reference to each registered
		resource.

		@@ -83,3 +88,4 @@ ```js

		An options object containing configuration. The following values can be provided:
		An options object containing configuration. The following values can be
		provided:

		@@ -141,3 +147,4 @@ - `retries` - {Number} - The number of times the client should retry to settle a version number conflict before terminating. See the section "[on retrying](#on-retrying)" for more information. Default: 4

		Retrieve list of all JavaScript references from all registered and fetched components.
		Retrieve list of all JavaScript references from all registered and fetched
		components.

		@@ -164,3 +171,4 @@ ```js

		Retrieve a list of all CSS references from all registered and fetched components.
		Retrieve a list of all CSS references from all registered and fetched
		components.

		@@ -295,3 +303,4 @@ ```js

		An options object containing configuration. The following values can be provided:
		An options object containing configuration. The following values can be
		provided:

		@@ -312,3 +321,4 @@ - `pathname` - {String} - A path which will be appended to the content root of the component when requested.

		An options object containing configuration. The following values can be provided:
		An options object containing configuration. The following values can be
		provided:

		@@ -321,4 +331,4 @@ - `pathname` - {String} - A path which will be appended to the content root of the component when requested.

		A property returning the name of the podium resource.
		This is the name provided during the call to `register`.
		A property returning the name of the podium resource. This is the name provided
		during the call to `register`.

		@@ -335,5 +345,5 @@ ### .uri
		By default all manifests are cached for 24 hours unless a new
		version of the manifest is detected by a change in the `podlet-version` HTTP header
		on the content URI. When this happens, the cache is thrown away and the fresh version of the
		manifest is cached.
		version of the manifest is detected by a change in the `podlet-version` HTTP
		header on the content URI. When this happens, the cache is thrown away and the
		fresh version of the manifest is cached.

		@@ -347,6 +357,5 @@ The default length of time the manifest is cached for can be configured

		It is also possible to control how long a manifest should be cached in
		the client from a Podium component. This is done by setting a [RFC 7234](https://tools.ietf.org/html/rfc7234)
		compatible HTTP header on the manifest on the server serving the
		Podium component.
		It is also possible to control how long a manifest should be cached in the
		client from a Podium component. This is done by setting a [RFC 7234] compatible
		HTTP header on the manifest on the server serving the Podium component.

		@@ -368,10 +377,11 @@ Example: This will cache the manifest for 1 hour:

		By default the client will never throw if something fails in the process
		of retreiving the manifest, the fallback or the content itself. It will
		simply provide a fallback if it has one or an empty String for the
		resource in an error situation.
		By default the client will never throw if something fails in the process of
		retreiving the manifest, the fallback or the content itself. It will simply
		provide a fallback if it has one or an empty String for the resource in an error
		situation.

		There are however, cases where throwing an error is more appropriate.
		This can be achieved by setting the option `throwable` to `true` in the `.register()` method.
		If an error is thrown in the process of retrieving the manifest, the fallback or the content then it can then be acted upon.
		There are however, cases where throwing an error is more appropriate. This can
		be achieved by setting the option `throwable` to `true` in the `.register()`
		method. If an error is thrown in the process of retrieving the manifest, the
		fallback or the content then it can then be acted upon.

		@@ -404,13 +414,12 @@ Example:

		In this example, the `catch` will be triggered if `bar` encounters
		an error in the process of retrieving content from the remote.
		If the same happens with `foo` the `catch` will NOT be triggered.
		In this example, the `catch` will be triggered if `bar` encounters an error in
		the process of retrieving content from the remote. If the same happens with
		`foo` the `catch` will NOT be triggered.

		When a resource is flagged as throwable and it throws an error the
		error will be an enriched [boom error object](https://github.com/hapijs/boom)
		with detailed information on what went wrong.
		When a resource is flagged as throwable and it throws an error the error will be
		an enriched [boom] with detailed information on what went wrong.

		The error object will reflect the http status code of the remote.
		In other words; if the remote responded with a 404, the `statusCode`
		in the error object will be 404.
		The error object will reflect the http status code of the remote. In other
		words; if the remote responded with a 404, the `statusCode` in the error object
		will be 404.

		@@ -423,17 +432,44 @@ ## On retrying

		Detection of updates to a component is done by the content route in the component
		serving an HTTP header with the same version number as in the component's manifest
		and if the client detects a difference between the HTTP header version number
		and the version in the manifest cached in the client, the component has changed.
		Detection of updates to a component is done by the content route in the
		component serving an HTTP header with the same version number as in the
		component's manifest and if the client detects a difference between the HTTP
		header version number and the version in the manifest cached in the client, the
		component has changed.

		In the event of an update the client will have to do multiple HTTP requests
		to refetch the manifest, fallback and content. In a distributed
		system there can be windows where a component can exist with two versions at
		the same time during a rolling deploy. In such a scenario the client might
		go into an "update loop" due to hitting different versions of the component.
		In the event of an update the client will have to do multiple HTTP requests to
		refetch the manifest, fallback and content. In a distributed system there can be
		windows where a component can exist with two versions at the same time during a
		rolling deploy. In such a scenario the client might go into an "update loop" due
		to hitting different versions of the component.

		In a rolling deploy this is not nessessery a bad thing. But to protect both
		the application using the client and the component itself, the client will terminate
		the process of updating if such an "update loop" is detected. How many times
		the client will retry settling an update before termination can be set by
		the `retries` argument in the client constructor and the `.register()` method.
		In a rolling deploy this is not nessessery a bad thing. But to protect both the
		application using the client and the component itself, the client will terminate
		the process of updating if such an "update loop" is detected. How many times the
		client will retry settling an update before termination can be set by the
		`retries` argument in the client constructor and the `.register()` method.

		## License

		Copyright (c) 2019 FINN.no

		Permission is hereby granted, free of charge, to any person obtaining a copy
		of this software and associated documentation files (the "Software"), to deal
		in the Software without restriction, including without limitation the rights
		to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
		copies of the Software, and to permit persons to whom the Software is
		furnished to do so, subject to the following conditions:

		The above copyright notice and this permission notice shall be included in all
		copies or substantial portions of the Software.

		THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
		IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
		FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
		AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
		LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
		OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
		SOFTWARE.

		[@podium/layout]: https://github.com/podium-lib/layout '@podium/layout'
		[rfc 7234]: https://tools.ietf.org/html/rfc7234 'RFC 7234'
		[boom]: https://github.com/hapijs/boom 'Boom'

@podium/client - npm Package Compare versions

New alerts

Fixed alerts

Improved metrics