README
fastly-native-promises
Native Promise based Fastly API client for Node.js
Problem
The callback-based fastly package is still the most used client on NPM. However, I needed a client which allows me to perform request sequentially and parallelly without ending up in an untamable callback hell. Philipp Schulte's fastly-native-promises client seemed almost perfect, except:
- it uses Axios, which is an additional dependency we'd like to avoid, especially when running inside Adobe I/O Runtime
- it has been missing features and pull requests were merged only slowly
This fork addresses the concerns above but breaks compatibility with Browsers, so that it can only be used in Node JS environments.
Solution
The fastly-native-promises
package uses the promise-based HTTP client Request-Promise-Native to perform requests to the Fastly API. Request-Promise-Native supports the native JavaScript Promise API and automatically transforms the data into JSON. Each fastly-native-promises
API method returns a Promise which represents either the completion or failure of the request.
Table of Contents
Security
You'll need a Fastly API Token to use the fastly-native-promises
library. I recommend using a token with global scope to be able to use all fastly-native-promises
API methods.
Install
This is a Node.js module available through the npm registry. Installation is done using the npm install
command:
$ npm install @adobe/fastly-native-promises
Changes
See the changelog.
Usage
const fastly = require('@adobe/fastly-native-promises');
// create one or more instances
const service_1 = fastly('token', 'service_id_1');
const serivce_2 = fastly('token', 'service_id_2');
// make changes
service_1.transact(async () => {
return this.writeS3('test-s3', {
name: 'test-s3',
bucket_name: 'my_corporate_bucket',
access_key: 'AKIAIOSFODNN7EXAMPLE',
secret_key: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
});
});
service_2.transact(async () => {
return this.writeBigquery('test-bq', {
name: 'test-bq',
format: '{\n "timestamp":"%{begin:%Y-%m-%dT%H:%M:%S}t",\n "time_elapsed":%{time.elapsed.usec}V,\n "is_tls":%{if(req.is_ssl, "true", "false")}V,\n "client_ip":"%{req.http.Fastly-Client-IP}V",\n "geo_city":"%{client.geo.city}V",\n "geo_country_code":"%{client.geo.country_code}V",\n "request":"%{req.request}V",\n "host":"%{req.http.Fastly-Orig-Host}V",\n "url":"%{json.escape(req.url)}V",\n "request_referer":"%{json.escape(req.http.Referer)}V",\n "request_user_agent":"%{json.escape(req.http.User-Agent)}V",\n "request_accept_language":"%{json.escape(req.http.Accept-Language)}V",\n "request_accept_charset":"%{json.escape(req.http.Accept-Charset)}V",\n "cache_status":"%{regsub(fastly_info.state, "^(HIT-(SYNTH)|(HITPASS|HIT|MISS|PASS|ERROR|PIPE)).*", "\\\\2\\\\3") }V"\n}',
user: 'fastly-bigquery-log@example-fastly-log.iam.gserviceaccount.com',
project_id: 'example-fastly-log',
dataset: 'fastly_log_test',
table: 'fastly_logs',
template_suffix: null,
secret_key: '-----BEGIN PRIVATE KEY-----\nMIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQC7bPG9yaIYd5AL\nmvOaYvNozFJB/VWS53KWBll769kJvlmgMks6r6Xrv8w6rjxWKjZeDrnXVf7UDa0F\nckPPIFvXRxahftWFMGArw0lIvQzgT4/BlndXU5RNxfah/8m7q/GIF6oNYWzfJwvv\nzodxDUqIRH2e2JWidNRjElHuogYHLhV4O/od5pAkfDwak/ihuuh/2VA3Auwb3nph\ndX2F0JBs14oPKZUTYUUSzUQY5IMxSxYUA4Q7W4v21x1EnJt+biXOrERk1rm4ieEE\nU3WkjR5c5gvG8xcWyYod87RNFELmIhCCytI1+t5C3Em/jPsQFtLzwHpbNhdW4oEm\nn7d06n75AgMBAAECggEAWRh26lNZfOwJS5sDRlbXgu/uAnSdI1JmxC6Mhz4cVGdq\nT57Y6DLrWuA4A4UkJYm3gorZiSXWF5PQthAVb/bf8bxXY7nZYpEWhnc09SD5aAAq\nREp0vMx8aWQ709K2YUJg+zDUo7u2d3YmVH8HH5TD43c7iDFJIIsNE3N4A0p+NxZ+\nw06FFW+fz/etrWiNyhrlTsbkMbSgU+GpFFBq1pCd0ni5d1YM1rsaAaUpmkwdjgjL\noDs+M/L/HtqfEhyZNdw8JF7EJXVE1bIl7/NL0rBInhyO28FcB56t/AG5nzXKFI/c\nc+IO7d6MOOqiGRLRWZItEpnyzuV8DZo461wy1hSvqQKBgQDhSsg2cHkTrtBW8x0A\n3BwB/ygdkkxm1OIvfioT+JBneRufUPvVIM2aPZBBGKEedDAmIGn/8f9XAHhKjs8B\nEsPRgE206s4+hnrTcK7AeWWPvM9FDkrkQCoJFuJrNy9mJt8gs7AnnoBa9u/J4naW\ne1tfC8fUfsa7kdzblDhcRQ8FhwKBgQDU+N4kPzIdUuJDadd6TkBbjUNPEfZzU5+t\nIike2VSRhApxAxviUnTDsTROwJRzKik9w7gIMka8Ek+nmLNMEtds77ttcGQRdu16\n+vT1iualiCJe+/iMbl+PiJtFwhEHECLU9QfgBVS6r2lDAlZA+w6nwCRiidlrObzO\nCXqVOzN3fwKBgAsrOuu//bClHP0ChnCReO38aU+1/gWnDiOOnKVq0DXhAiaOzD1P\nqAG6hZlEkFBDMPWzq62doKv+gPgpRkfmV0DenHuYnGrrHdG3p2IxYoCSuq/QupPA\nPpU+xjDMhpQI30zuu4/rQq+/yDl4+aoSKYB3xAtb0Zxg6dMU8QpZ/hmnAoGBAIFu\nIesbcQR7O8FGkMrmxZweNNrYCtQ57R/WU/FImWm6OnJGNmsMO6Q2jJiT12RKKjg8\nOxrYGz7vTfOIDOddyAiPhXPUSyyF/3uvCrIzUUsmeeUJ8xq9dVwQ5HS3pYuKVfDg\nXYHbG4w9UJaF1A+3xEdUsYglSLouo7z/67zH9tZXAoGBAKpsdjSd3R+llaAv2HQ8\nGMlN92UTr5i9w++QMXq4qspH5NEYqz3NHbKuYthZqxEsRUZbRP50eDWU4jvxFVJl\nLBFINp6B+3AsIme0YCyOaleB/Cy0347miSinSv2I6QiH6dQxHdHzrG+x1evS/76f\nKT0KS+ySjCAEWgg4v+mjUDUV\n-----END PRIVATE KEY-----\n',
response_condition: '',
});
// optional, but speeds up end of process
await service_1.discard();
await service_2.discard();
});
Promises
Purge all domains of the active version:
- Get all the versions.
- Filter out the active version.
- Get all the domains for the active version.
- Purge all the domains.
- Log the status text for each purge request.
const fastly = require('fastly-native-promises');
const service = fastly('token', 'service_id');
function handler() {
service.readVersions()
.then(versions => {
const active = versions.data.filter(version => version.active)[0];
return service.readDomains(active.number);
})
.then(domains => {
return Promise.all(domains.data.map(domain => service.purgeIndividual(domain.name)));
})
.then(purges => {
purges.forEach(purge => console.log(purge.statusText));
})
.catch(e => {
console.log('Shoot!');
});
}
Async/Await
Update first_byte_timeout
property for every backend and service if the value is less than 5000 milliseconds:
- Get all the services associated with the Fastly API token.
- Filter out the service IDs.
- Iterate over all services synchronously.
- Get all the versions.
- Filter out the active version.
- Get all the backends for the active version.
- Filter out the affected backends.
- Continue with the next service if there are no affected backends.
- Clone the active version.
- Update all the affected backends parallelly.
- Activate the cloned version.
const fastly = require('fastly-native-promises');
const account = fastly('token');
async function handler() {
try {
const services = await account.readServices();
const ids = services.data.map(service => service.id);
for (const id of ids) {
const service = fastly('token', id);
const versions = await service.readVersions();
const active = versions.data.filter(version => version.active)[0];
const backends = await service.readBackends(active.number);
const affected = backends.data.filter(backend => backend.first_byte_timeout < 5000);
if (!affected.length) continue;
const clone = await service.cloneVersion(active.number);
await Promise.all(affected.map(backend => service.updateBackend(clone.data.number, backend.name, { first_byte_timeout: 5000 })));
await service.activateVersion(clone.data.number);
}
} catch (e) {
console.log('Shoot!');
}
}
Response Schema
Each fastly-native-promises
API method returns the following response object:
{
// the HTTP status code from the server response
status: 200,
// the HTTP status message from the server response
statusText: 'OK',
// the headers that the server responded with
headers: {},
// the options that were provided to request for the request
config: {},
// the request that generated the response
request: {},
// the response that was provided by the server
data: {}
}
Retrieving Request Statistics
The Fastly
instance has a requestmonitor
property that can be used to retrieve request statistics:
requestmonitor.count
for the total number of requests.requestmonitor.remaining
for the number of requests remaining according to Fastly's API Rate limit for the hour orundefined
(if no modifying requests have been made yet).requestmonitor.edgedurations
for an array of API processing durations (in milliseconds, measured from the edge).requestmonitor.durations
for an array of request durations (in milliseconds, measured from the client, i.e. including network latency).
With requestmonitor.stats
you can get all of that in one object, including minimum, maximum and mean durations for all requests.
Guarding against Rate Limits
Using the requestmonitor.remaining
property, you can make sure that you still have sufficient requests before you hit the rate limit.
When using the instance.transact
method, you can furthermore provide a minimum for the necessary available request limit so that after the initial cloning of the version no additional requests will be made if the API rate limit will be exceeded. This allows you to fail fast in case of rate limit issues.
High-Level Helpers
While most functionality is a low-level wrapper of the Fastly, API, we provide a couple of higher-level helper functions in properties of the Fastly
instance.
fastly.conditions
Conditions Helper in The conditions helper eases the creation and management of conditions.
const fastly = require('fastly-native-promises');
const instance = fastly('mykey', 'service-config');
const update = fastly.conditions.update(1, 'REQUEST', 'Created as an Example', 'example');
const conditions = await update('req.url.basename == "new.html"', 'req.url.basename == "index.html"');
console.log('Created a condition matching index.html with following name', conditions['req.url.basename == "index.html"'].name);
fastly.conditions.update
can be called with the parameters version
(service config version), type
(condition type, either REQUEST
, RESPONSE
, or CACHE
), comment
(a comment that will be visible in the Fastly UI), nameprefix
(a common prefix for the condition name) to get a new function update
that performs the update.
When update
is called with a list of statements
in VCL condition language, it will synchronize the list of conditions passed in with the conditions that already exist in the Fastly service config. All conditions that share the same nameprefix
, but are no longer used get deleted, new conditions that don't exist yet will get created (unchanged conditions aren't touched, reducing the number of requests made upon updates).
The return value of update
is an object that maps condition statement to the condition object. This allows re-using the condition in other Fastly API calls.
fastly.headers
Header Helper in The headers helper eases the creation and management of conditional headers.
const fastly = require('fastly-native-promises');
const instance = fastly('mykey', 'service-config');
const update = fastly.headers.update(
1,
'REQUEST', // apply a request condition
'Created as an Example', // use following comment for conditions
'example', // name-prefix for all generated conditions and headers
'set', // set the header
'http.Location' // which header (Location)
'request' // in the request handling
);
await update(
{
condition: 'req.url.basename == "new.html"',
expression: '"https://new.example.com"',
},
{
condition: 'req.url.basename == "index.html"',
expression: 'https://www.example.com',
});
fastly.headers.update
can be called with the parameters version
(service config version), type
(condition type, either REQUEST
, RESPONSE
, or CACHE
), comment
(a comment that will be visible in the Fastly UI), nameprefix
(a common prefix for the condition name), action
(what to do with the header, can be set
, append
, or delete
), header
(the name of the header – remember to include http.
in the value), sub
(the subroutine where the header is applied, can be request
, fetch
, cache
, or response
) to get a new function update
that performs the update.
When update
is called with a list of objects
that looks like { condition: 'req.url ~ "foo/(.*)/bar"', expression: '"bar/" + re.group.1 + "/foo"'}
, i.e. pairs of a condition
(in VCL condition language) and an expression
(also valid VCL), it will synchronize the list of headers (and resultant conditions) passed in with the headers and conditions that already exist in the Fastly service config. All conditions and headers that share the same nameprefix
, but are no longer used get deleted, new conditions and headers that don't exist yet will get created (unchanged conditions and headers aren't touched, reducing the number of requests made upon updates).
API
Classes
- AccountAPI :
AccountAPI
The Fastly Account API.
- AuthAPI :
AuthAPI
The Fastly Auth API.
- DomainAPI :
DomainAPI
The Fastly Domain API.
- HealthcheckAPI :
HealthcheckAPI
The Fastly Healthcheck API.
- PurgeAPI :
PurgeAPI
The Fastly Purge API.
- Conditions
Helper class with high-level operations for condition-management.
- Headers
Helper class with high-level operations for condition-management.
- Fastly
Functions
- repeat(responseOrError) ⇒
boolean
Determines if a response or error indicates that the response is repeatable.
Typedefs
- CreateFunction ⇒
Promise
A function that creates a resource of a specific type. If a resource of that name already exists, it will reject the returned promise with an error.
- UpdateFunction ⇒
Promise
A function that updates an already existing resource of a specific type. If no resource of that name exists, it will reject the returned promise with an error.
- ReadFunction ⇒
Promise
A function that retrieves a representation of a resource of a specific type. If no resource of that name exists, it will reject the returned promise with an error.
- ListFunction ⇒
Promise
A function that retrieves a list of resources of a specific type.
- FastlyError :
object
The FastlyError class describes the most common errors that can occur when working with the Fastly API. Using
error.status
, the underlying HTTP status code can be retrieved. Known error status codes include:- 400: attempting to activate invalid VCL
- 401: invalid credentials
- 404: resource not found
- 409: confict when trying to POST a resource that already exists
- 422: attempting to modify a service config that is not checked out
- 429: rate limit exceeded, try again later
- Response :
object
- Versions :
object
Describes the most relevant versions of the service.
- DictUpdate :
object
Specifies a dictionary update operation. In most cases,
upsert
is the best way to update values, as it will work for existing and non-existing items.- Snippet :
object
- VCL :
object
AccountAPI
AccountAPI : The Fastly Account API.
Kind: global class
See: https://docs.fastly.com/api/account#top
- AccountAPI :
AccountAPI
- .readCurrentUser() ⇒
Promise
- .readUsers() ⇒
Promise
- .readUser(id) ⇒
Promise
- .createUser(name, login) ⇒
Promise
- .readInvitations() ⇒
Promise
- .createInvitation(email, role) ⇒
Promise
- .acceptInvitation(acceptCode, name, password) ⇒
Promise
- .deleteInvitation(id) ⇒
Promise
- .readCurrentUser() ⇒
Promise
accountAPI.readCurrentUser() ⇒ Get the currently logged in user.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#user_91db9d9178f3f4c7597899942bd3f941
Promise
accountAPI.readUsers() ⇒ Get a list of all users from the current customer.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#customer_12f4a69627ba3bbb1c8668aae03a60ad
Promise
accountAPI.readUser(id) ⇒ Get the the user with the specific id.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#user_15a6c72980b9434ebb8253c7e882c26c
Param | Type | Description |
---|---|---|
id | string |
The User ID. |
Promise
accountAPI.createUser(name, login) ⇒ Create a user.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#user_00b606002596bac1c652614de98bd260
Param | Type | Description |
---|---|---|
name | string |
The user name. |
login | string |
The user login. |
Promise
accountAPI.readInvitations() ⇒ List all invitations.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#invitations_6d8623de97ed7e50b7b6498e374bb657
Promise
accountAPI.createInvitation(email, role) ⇒ Create an invitation.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#invitations_8c4da3ca11c75facd36cfaad024bd891
Param | Type | Default | Description |
---|---|---|---|
string |
The email address for the invitation. | ||
role | string |
"engineer" |
The user role. Defaults to {@code engineer}. |
Promise
accountAPI.acceptInvitation(acceptCode, name, password) ⇒ Accept an invitation.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
Param | Type | Description |
---|---|---|
acceptCode | string |
The accept code retrieved in the email. |
name | string |
Name for the new user. |
password | string |
Password for the new user. |
Promise
accountAPI.deleteInvitation(id) ⇒ Delete an invitation.
Kind: instance method of AccountAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/account#invitations_d70a7460c7e1bd8dd660c6f5b3558c2e
Param | Type | Description |
---|---|---|
id | string |
The invitation id. |
AuthAPI
AuthAPI : The Fastly Auth API.
Kind: global class
See: https://docs.fastly.com/api/auth#top
- AuthAPI :
AuthAPI
- .readTokens([customerId]) ⇒
Promise
- .readToken([id]) ⇒
Promise
- .deleteToken([id]) ⇒
Promise
- .createToken(options) ⇒
Promise
- .readTokens([customerId]) ⇒
Promise
authAPI.readTokens([customerId]) ⇒ List all tokens of a customer.
Kind: instance method of AuthAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_d59ff8612bae27a2317278abb048db0c
Param | Type | Description |
---|---|---|
[customerId] | string |
The id of the customer. |
Promise
authAPI.readToken([id]) ⇒ Get the token with the specified id. If the Id is missing, the self token is returned.
Kind: instance method of AuthAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_bb00e7ed542cbcd7f32b5c908b8ce244
Param | Type | Description |
---|---|---|
[id] | string |
The token id. |
Promise
authAPI.deleteToken([id]) ⇒ Delete the token with the specified id.
Kind: instance method of AuthAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_4a958ba69402500937f0d8570f7ce86f
Param | Type | Description |
---|---|---|
[id] | string |
The token id. |
Promise
authAPI.createToken(options) ⇒ Create an API token.
Kind: instance method of AuthAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/auth#tokens_db4655a45a0107448eb0676577446e40
Param | Type | Description |
---|---|---|
options | object |
The token options. |
DomainAPI
DomainAPI : The Fastly Domain API.
Kind: global class
See: https://docs.fastly.com/api/config#domain
- DomainAPI :
DomainAPI
- .domainCheck(version, name) ⇒
Promise
- .domainCheckAll(version) ⇒
Promise
- .readDomains(version) ⇒
Promise
- .readDomain(version, name) ⇒
Promise
- .readServiceDomains([serviceId]) ⇒
Promise
- .createDomain(version, name, comment) ⇒
Promise
- .updateDomain(version, oldName, name, comment) ⇒
Promise
- .deleteDomain(version, name) ⇒
Promise
- .domainCheck(version, name) ⇒
Promise
domainAPI.domainCheck(version, name) ⇒ Checks the status of all domains for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_30a3f14c9a0ce5730757d39983ab7dc6
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The name of the domain. |
Promise
domainAPI.domainCheckAll(version) ⇒ Checks the status of all domains for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_e33a599694c3316f00b6b8d53a2db7d9
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
Example
instance.domainCheckAll('182')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
domainAPI.readDomains(version) ⇒ List all the domains for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_6d340186666771f022ca20f81609d03d
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
Example
instance.readDomains('182')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
domainAPI.readDomain(version, name) ⇒ List all the domains for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_f1b5fab17a0729daeeaf7594b47759c5
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The domain name. |
Promise
domainAPI.readServiceDomains([serviceId]) ⇒ List the domains within a service.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#service_d5578a1e3bc75512711ddd0a58ce7a36
Param | Type | Description |
---|---|---|
[serviceId] | string |
The service id. |
Promise
domainAPI.createDomain(version, name, comment) ⇒ Create a domain for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_90345101274774ff1b84f0a7dd010b01
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The domain name. |
comment | string |
Optional comment. |
Promise
domainAPI.updateDomain(version, oldName, name, comment) ⇒ Update a domain for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_2ef42bd9b4c56c86b46dc0e36096ab10
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
oldName | string |
The old name of the domain. |
name | string |
The domain name. |
comment | string |
Optional comment. |
Promise
domainAPI.deleteDomain(version, name) ⇒ Delete the domain for a particular service and version.
Kind: instance method of DomainAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#domain_aab5a322f58df2b1db8dc276e8594a70
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The domain name. |
HealthcheckAPI
HealthcheckAPI : The Fastly Healthcheck API.
Kind: global class
See: https://docs.fastly.com/api/config#healthcheck
- HealthcheckAPI :
HealthcheckAPI
- .readHealthchecks(version) ⇒
Promise
- .readHealthcheck(version, name) ⇒
Promise
- .createHealthcheck(version, data) ⇒
Promise
- .updateHealthcheck(version, name, data) ⇒
Promise
- .deleteHealthcheck(version, name) ⇒
Promise
- .readHealthchecks(version) ⇒
Promise
healthcheckAPI.readHealthchecks(version) ⇒ List all healthchecks for a particular service and version.
Kind: instance method of HealthcheckAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_126cb37382d68583269420ba772ded36
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
Promise
healthcheckAPI.readHealthcheck(version, name) ⇒ Get details of a single named healthcheck.
Kind: instance method of HealthcheckAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_b54ea357a2377e62ae7649e609b94966
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The name of the healthcheck. |
Promise
healthcheckAPI.createHealthcheck(version, data) ⇒ Create a healthcheck for a particular service and version.
Kind: instance method of HealthcheckAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_8712be8923dd419c54393da3ac31f6d3
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
data | object |
The healthcheck definition. |
Promise
healthcheckAPI.updateHealthcheck(version, name, data) ⇒ Update the healthcheck for a particular service and version.
Kind: instance method of HealthcheckAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_9a60b6005125c4afeaa80111e69d7586
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The name of the healthcheck to update. |
data | object |
The healthcheck definition. |
Promise
healthcheckAPI.deleteHealthcheck(version, name) ⇒ Delete the healthcheck for a particular service and version.
Kind: instance method of HealthcheckAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#healthcheck_a22900c40a2fd59db5028061dc5dfa36
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The name of the healthcheck to delete. |
PurgeAPI
PurgeAPI : The Fastly Purge API.
Kind: global class
See: https://docs.fastly.com/api/purge#purge
- PurgeAPI :
PurgeAPI
- .purgeIndividual(url) ⇒
Promise
- .purgeAll() ⇒
Promise
- .purgeKey(key) ⇒
Promise
- .purgeKeys(keys) ⇒
Promise
- .softPurgeIndividual(url) ⇒
Promise
- .softPurgeKey(key) ⇒
Promise
- .softPurgeKeys(keys) ⇒
Promise
- .purgeIndividual(url) ⇒
Promise
purgeAPI.purgeIndividual(url) ⇒ Instant Purge an individual URL.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_3aa1d66ee81dbfed0b03deed0fa16a9a
Param | Type | Description |
---|---|---|
url | string |
The URL to purge. |
Example
instance.purgeIndividual('www.example.com')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
purgeAPI.purgeAll() ⇒ Instant Purge everything from a service.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_bee5ed1a0cfd541e8b9f970a44718546
Example
instance.purgeAll()
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
purgeAPI.purgeKey(key) ⇒ Instant Purge a particular service of items tagged with a Surrogate Key.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_d8b8e8be84c350dd92492453a3df3230
Param | Type | Description |
---|---|---|
key | string |
The surrogate key to purge. |
Example
instance.purgeKey('key_1')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
purgeAPI.purgeKeys(keys) ⇒ Instant Purge a particular service of items tagged with Surrogate Keys in a batch.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_db35b293f8a724717fcf25628d713583
Param | Type | Description |
---|---|---|
keys | Array |
The array of surrogate keys to purge. |
Example
instance.purgeKeys(['key_2', 'key_3', 'key_4'])
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
purgeAPI.softPurgeIndividual(url) ⇒ Soft Purge an individual URL.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#soft_purge_0c4f56f3d68e9bed44fb8b638b78ea36
Param | Type | Description |
---|---|---|
url | string |
The URL to soft purge. |
Example
instance.softPurgeIndividual('www.example.com/images')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
purgeAPI.softPurgeKey(key) ⇒ Soft Purge a particular service of items tagged with a Surrogate Key.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#soft_purge_2e4d29085640127739f8467f27a5b549
Param | Type | Description |
---|---|---|
key | string |
The surrogate key to soft purge. |
Example
instance.softPurgeKey('key_5')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
purgeAPI.softPurgeKeys(keys) ⇒ Soft Purge a particular service of items tagged with Surrogate Keys in a batch.
Kind: instance method of PurgeAPI
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/purge#purge_db35b293f8a724717fcf25628d713583
Param | Type | Description |
---|---|---|
keys | Array |
The array of surrogate keys to purge. |
Example
instance.softPurgeKeys(['key_2', 'key_3', 'key_4'])
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Conditions
Helper class with high-level operations for condition-management.
Array.<function()>
conditions.multistepupdate(version, type, commentprefix, nameprefix) ⇒ Creates functions for multi-step creation of missing and deletion of superflous conditions.
Kind: instance method of Conditions
Returns: Array.<function()>
- A pair of a create and cleanup function.
Param | Type | Description |
---|---|---|
version | number |
Service config version. |
type | string |
Condition type, can be REQUEST , RESPONSE , or CACHE . |
commentprefix | string |
The prefix to be used for comments. |
nameprefix | string |
- The prefix to be used for names. |
Headers
Helper class with high-level operations for condition-management.
Array.<function()>
headers.update(version, type, commentprefix, nameprefix, action, header, sub) ⇒ Creates functions for multi-step creation of missing and deletion of superflous conditional headers.
Kind: instance method of Headers
Returns: Array.<function()>
- A pair of a create and cleanup function.
Param | Type | Description |
---|---|---|
version | number |
Service config version. |
type | string |
Condition type, can be REQUEST , RESPONSE , or CACHE . |
commentprefix | string |
The prefix to be used for comments. |
nameprefix | string |
- The prefix to be used for names. |
action | string |
What do do with the header, can be set , append , delete . |
header | string |
The name of the header to set. |
sub | string |
Name of the subroutine where the header should be applied, can be request , fetch , cache , or response . |
Fastly
Kind: global class
- Fastly
- new Fastly(token, service_id, timeout)
- .readLogsFn(service) ⇒
ListFunction
- .readLogFn(service) ⇒
ReadFunction
- .createLogFn(service) ⇒
CreateFunction
- .updateLogFn(service) ⇒
UpdateFunction
- .upsertFn(createFn, updateFn, readFn) ⇒
UpdateFunction
- .discard()
- .dataCenters() ⇒
Promise
- .publicIpList() ⇒
Promise
- .edgeCheck(url) ⇒
Promise
- .readServices() ⇒
Promise
- .readServicesById() ⇒
Promise
- .readService([serviceId]) ⇒
Promise
- .readVersions() ⇒
Promise
- .getVersions() ⇒
Versions
- .cloneVersion(version) ⇒
Promise
- .activateVersion(version) ⇒
Promise
- .readDictItems(version, name) ⇒
Promise
- .readDictItem(version, name, key) ⇒
Promise
- .createDictItem(version, name, key, value) ⇒
Promise
- .bulkUpdateDictItems(version, name, ...items) ⇒
Promise
- .updateDictItem(version, name, key, value) ⇒
Promise
- .deleteDictItem(version, name, key) ⇒
Promise
- .writeDictItem(version, name, key, value) ⇒
Promise
- .readDictionaries(version) ⇒
Promise
- .readDictionary(version, name) ⇒
Promise
- .createDictionary(version, data) ⇒
Promise
- .updateDictionary(version, name, data) ⇒
Promise
- .deleteDictionary(version, name) ⇒
Promise
- .readConditions(version) ⇒
Promise
- .readCondition(version, name) ⇒
Promise
- .readSnippet(version, name) ⇒
Promise
- .createCondition(version, data) ⇒
Promise
- .updateCondition(version, name, data) ⇒
Promise
- .deleteCondition(version, name) ⇒
Promise
- .readHeaders(version) ⇒
Promise
- .readHeader(version, name) ⇒
Promise
- .createHeader(version, data) ⇒
Promise
- .updateHeader(version, name, data) ⇒
Promise
- .deleteHeader(version, name) ⇒
Promise
- .readBackends(version) ⇒
Promise
- .updateBackend(version, name, data) ⇒
Promise
- .createBackend(version, data) ⇒
Promise
- .readSnippets(version) ⇒
Promise
- .createSnippet(version, data) ⇒
Promise
- .updateSnippet(version, name, data) ⇒
Promise
- .createVCL(version, data) ⇒
Promise
- .updateVCL(version, name, data) ⇒
Promise
- .setMainVCL(version, name) ⇒
Promise
- .transact(operations, activate, limit) ⇒
object
- .dryrun(operations) ⇒
object
new Fastly(token, service_id, timeout)
The constructor method for creating a fastly-promises instance.
Param | Type | Default | Description |
---|---|---|---|
token | string |
The Fastly API token. | |
service_id | string |
The Fastly service ID. | |
timeout | number |
15000 |
HTTP timeout for requests to the Fastly API, default: 15 seconds. |
ListFunction
fastly.readLogsFn(service) ⇒ Create a new function that lists all log configurations for a given service and version. The function can be parametrized with the name of the logging service.
Kind: instance method of Fastly
Returns: ListFunction
- A logging function.
Param | Type | Description |
---|---|---|
service | string |
The id of the logging service. Supported services are: s3, s3canary, azureblob, cloudfiles, digitalocean, ftp, bigquery, gcs, honeycomb, logshuttle, logentries, loggly, heroku, https, openstack, papertrail, scalyr, splunk, sumologic, syslog. |
ReadFunction
fastly.readLogFn(service) ⇒ Create a new function that returns a named log configuration for a given service and version. The function can be parametrized with the name of the logging service.
Kind: instance method of Fastly
Returns: ReadFunction
- A logging function.
Param | Type | Description |
---|---|---|
service | string |
The id of the logging service. Supported services are: s3, s3canary, azureblob, cloudfiles, digitalocean, ftp, bigquery, gcs, honeycomb, logshuttle, logentries, loggly, heroku, https, openstack, papertrail, scalyr, splunk, sumologic, syslog. |
CreateFunction
fastly.createLogFn(service) ⇒ Create a new function that creates a named log configuration for a given service and version. The function can be parametrized with the name of the logging service.
Kind: instance method of Fastly
Returns: CreateFunction
- A logging function.
Param | Type | Description |
---|---|---|
service | string |
The id of the logging service. Supported services are: s3, s3canary, azureblob, cloudfiles, digitalocean, ftp, bigquery, gcs, honeycomb, logshuttle, logentries, loggly, heroku, https, openstack, papertrail, scalyr, splunk, sumologic, syslog. |
UpdateFunction
fastly.updateLogFn(service) ⇒ Create a new function that updates a named log configuration for a given service and version. The function can be parametrized with the name of the logging service.
Kind: instance method of Fastly
Returns: UpdateFunction
- A logging function.
Param | Type | Description |
---|---|---|
service | string |
The id of the logging service. Supported services are: s3, s3canary, azureblob, cloudfiles, digitalocean, ftp, bigquery, gcs, honeycomb, logshuttle, logentries, loggly, heroku, https, openstack, papertrail, scalyr, splunk, sumologic, syslog. |
UpdateFunction
fastly.upsertFn(createFn, updateFn, readFn) ⇒ Creates an update-or-create or "safe create" function that will either create (if it does not exist) or update (if it does) a named resource. The function will attempt to check if the resource exists first (if a reader function has been provided), alternatively, it will just blindly create and fall back with an update.
Kind: instance method of Fastly
Returns: UpdateFunction
- An update function that does not fail on conflict.
Param | Type | Description |
---|---|---|
createFn | CreateFunction |
A function that creates a resource. |
updateFn | UpdateFunction |
A function that updates a resource. |
readFn | ReadFunction |
An optional function that checks for the existence of a resource. |
fastly.discard()
Free resources bound to the HTTP client (pending sessions/sockets) and allow the node process to quit.
Kind: instance method of Fastly
Returns: Promise
- A promise which resolves when all resources have been freed.
Promise
fastly.dataCenters() ⇒ Get a list of all Fastly datacenters.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/tools#datacenter_1c8d3b9dd035e301155b44eae05e0554
Example
instance.dataCenters()
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.publicIpList() ⇒ Fastly's services IP ranges.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/tools#public_ip_list_ef2e9900a1c9522b58f5abed92ec785e
Example
instance.publicIpList()
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.edgeCheck(url) ⇒ Retrieve headers and MD5 hash of the content for a particular URL from each Fastly edge server.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/tools#content_4d2d4548b29c7661e17ebe7098872d6d
Param | Type | Description |
---|---|---|
url | string |
Full URL (host and path) to check on all nodes. If protocol is omitted, http will be assumed. |
Example
instance.edgeCheck('api.example.com')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.readServices() ⇒ List all services.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#service_74d98f7e5d018256e44d1cf820388ef8
Example
instance.readServices()
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.readServicesById() ⇒ Reads the services and returns a data object that contains a map where the service id is the key.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
Promise
fastly.readService([serviceId]) ⇒ Get a specific service by id.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#service_a884a9abd5af9723f6fcbb1ed13ae4cc
Param | Type | Description |
---|---|---|
[serviceId] | string |
The service id. |
Promise
fastly.readVersions() ⇒ List the versions for a particular service.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#version_dfde9093f4eb0aa2497bbfd1d9415987
Example
instance.readVersions()
.then(res => {
const active = res.data.filter(version => version.active);
console.log(active);
})
.catch(err => {
console.log(err.message);
});
Versions
fastly.getVersions() ⇒ Gets the version footprint for the service.
Kind: instance method of Fastly
Returns: Versions
- The latest, current, and active versions of the service.
Promise
fastly.cloneVersion(version) ⇒ Clone the current configuration into a new version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#version_7f4937d0663a27fbb765820d4c76c709
Param | Type | Description |
---|---|---|
version | string |
The version to be cloned. |
Example
instance.cloneVersion('45')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.activateVersion(version) ⇒ Activate the current version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#version_0b79ae1ba6aee61d64cc4d43fed1e0d5
Param | Type | Description |
---|---|---|
version | string |
The version to be activated. |
Example
instance.activateVersion('23')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.readDictItems(version, name) ⇒ List all dictionary items for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_item_a48de28cd7e76c1ea58523f39bb7204b
Param | Type | Description |
---|---|---|
version | string |
The version of the dictionary. |
name | string |
The name of the dictionary. |
Example
instance.readDictItems(1, 'my_dictionary')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.readDictItem(version, name, key) ⇒ Get details of a single dictionary item.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_item_08f090cd03ed4602ae63f131087e2f29
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
Name of the dictionary. |
key | string |
The key to retrieve values by. |
Example
instance.readDictItem('12', 'extensions', 'some_key')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.createDictItem(version, name, key, value) ⇒ Create a new dictionary item for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The reponse object.
See: https://docs.fastly.com/api/config#dictionary_item_6ec455c0ba1b21671789e1362bc7fe55
Param | Type | Description |
---|---|---|
version | number |
The version number (current if omitted). |
name | object |
The dictionary definition. |
key | string |
The key. |
value | string |
The value to write. |
Promise
fastly.bulkUpdateDictItems(version, name, ...items) ⇒ Updates multiple dictionary items in bulk.
Kind: instance method of Fastly
Returns: Promise
- The response object.
Param | Type | Description |
---|---|---|
version | number |
The version numer (current if ommitted). |
name | string |
Name of the dictionary. |
...items | DictUpdate |
The dictionary update operations. |
Example
// single item
fastly.bulkUpdateDictItems(1, 'secret_dictionary',
{ item_key: 'some_key', item_value: 'some_value', op: 'upsert' });
// multiple items
fastly.bulkUpdateDictItems(1, 'secret_dictionary',
{ item_key: 'some_key', item_value: 'some_value', op: 'update' },
{ item_key: 'other_key', item_value: 'other_value', op: 'update' });
Promise
fastly.updateDictItem(version, name, key, value) ⇒ Update a dictionary item value for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_item_34c884a7cdce84dfcfd38dac7a0b5bb0
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The name of the dictionary. |
key | string |
The key to update data under. |
value | string |
The value to update the dictionary with. |
Example
instance.updateDictItem(1, 'extensions', 'html', 'text/html')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.deleteDictItem(version, name, key) ⇒ Delete a dictionary item for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_item_664347e743b8eafc9a93c729d9da0427
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
The name of the dictionary. |
key | string |
The key to update data under. |
Example
instance.deleteDictItem('34', 'extensions', 'html')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.writeDictItem(version, name, key, value) ⇒ Safely create, update or delete a dictionary item in a named dictionary.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
Param | Type | Description |
---|---|---|
version | number |
Service version to use for dictionary lookup. |
name | string |
Name of the dictionary (not ID). |
key | string |
Key to create, update or delete. |
value | string |
Value to update. Empty strings will delete the dictionary entry. |
Promise
fastly.readDictionaries(version) ⇒ List all dictionaries for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_6d2cc293b994eb8c16d93e92e91f3915
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
Example
instance.readDictionaries('12')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.readDictionary(version, name) ⇒ Get details of a single dictionary.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_0e16df083830ed3b6c30b73dcef64014
Param | Type | Description |
---|---|---|
version | string |
The current version of a service. |
name | string |
Name of the dictionary. |
Example
instance.readDictionary('12', 'extensions')
.then(res => {
console.log(res.data);
})
.catch(err => {
console.log(err.message);
});
Promise
fastly.createDictionary(version, data) ⇒ Create a new dictionary for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The reponse object.
See: https://docs.fastly.com/api/config#dictionary_7d48b87bf82433162a3b209292722125
Param | Type | Description |
---|---|---|
version | number |
The version number (current if omitted). |
data | object |
The dictionary definition. |
Promise
fastly.updateDictionary(version, name, data) ⇒ Update a dictionary for a particular service and version.
Kind: instance method of Fastly
Returns: Promise
- The response object representing the completion or failure.
See: https://docs.fastly.com/api/config#dictionary_8c9da370b1591d99e5389143a5589a32
Param | Type | Description |
---|---|---|
version | string |
The current version of a s |