ghost 5.8.1 → 5.9.0

package/core/server/api/README.md

@@ -1,130 +0,0 @@
-# API
-
-## Stages
-
-Each request goes through the following stages:
-
-- input validation
-- input serialisation
-- permissions
-- query
-- output serialisation
-
-The framework we are building pipes a request through these stages in respect of the API controller configuration.
-
-
-## Frame
-
-Is a class, which holds all the information for request processing. We pass this instance by reference.
-Each function can modify the original instance. No need to return the class instance.
-
-### Structure
-
-```
-{
-  original: Object,
-  options: Object,
-  data: Object,
-  user: Object,
-  file: Object,
-  files: Array
-}
-```
-
-### Example
-
-```
-{
-  original: {
-    include: 'tags'
-  },
-  options: {
-    withRelated: ['tags']
-  },
-  data: {
-    posts: []
-  }
-}
-```
-
-## API Controller
-
-A controller is no longer just a function, it's a set of configurations.
-
-### Structure
-
-```
-edit: function || object
-```
-
-```
-edit: {
-  headers: object,
-  options: Array,
-  data: Array,
-  validation: object | function,
-  permissions: boolean | object | function,
-  query: function
-}
-```
-
-### Examples
-
-
-```
-edit: {
-  headers: {
-    cacheInvalidate: true
-  },
-  // Allowed url/query params
-  options: ['include']
-  // Url/query param validation configuration
-  validation: {
-    options: {
-      include: {
-        required: true,
-        values: ['tags']
-      }
-    }
-  },
-  permissions: true,
-  // Returns a model response!
-  query(frame) {
-    return models.Post.edit(frame.data, frame.options);
-  }
-}
-```
-
-```
-read: {
-  // Allowed url/query params, which will be remembered inside `frame.data`
-  // This is helpful for READ requests e.g. `model.findOne(frame.data, frame.options)`.
-  // Our model layer requires sending the where clauses as first parameter.
-  data: ['slug']
-  validation: {
-    data: {
-      slug: {
-        values: ['eins']
-      }
-    }
-  },
-  permissions: true,
-  query(frame) {
-    return models.Post.findOne(frame.data, frame.options);
-  }
-}
-```
-
-```
-edit: {
-  validation() {
-    // custom validation, skip framework
-  },
-  permissions: {
-    unsafeAttrs: ['author']
-  },
-  query(frame) {
-    return models.Post.edit(frame.data, frame.options);
-  }
-}
-```

package/core/server/api/shared/frame.js

@@ -1,95 +0,0 @@
-const debug = require('@tryghost/debug')('api:shared:frame');
-const _ = require('lodash');
-
-/**
- * @description The "frame" holds all information of a request.
- *
- * Each party can modify the frame by reference.
- * A request hits a lot of stages in the API implementation and that's why modification by reference was the
- * easiest to use. We always have access to the original input, we never loose track of it.
- */
-class Frame {
-    constructor(obj = {}) {
-        this.original = obj;
-
-        /**
-         * options:     Query params, url params, context and custom options
-         * data:        Body or if the ctrl wants query/url params inside body
-         * user:        Logged in user
-         * file:        Uploaded file
-         * files:       Uploaded files
-         * apiType:     Content or admin api access
-         */
-        this.options = {};
-        this.data = {};
-        this.user = {};
-        this.file = {};
-        this.files = [];
-        this.apiType = null;
-    }
-
-    /**
-     * @description Configure the frame.
-     *
-     * If you instantiate a new frame, all the data you pass in, land in `this.original`. This is helpful
-     * for debugging to see what the original input was.
-     *
-     * This function will prepare the incoming data for further processing.
-     * Based on the API ctrl implemented, this fn will pick allowed properties to either options or data.
-     */
-    configure(apiConfig) {
-        debug('configure');
-
-        if (apiConfig.options) {
-            if (typeof apiConfig.options === 'function') {
-                apiConfig.options = apiConfig.options(this);
-            }
-
-            if (Object.prototype.hasOwnProperty.call(this.original, 'query')) {
-                Object.assign(this.options, _.pick(this.original.query, apiConfig.options));
-            }
-
-            if (Object.prototype.hasOwnProperty.call(this.original, 'params')) {
-                Object.assign(this.options, _.pick(this.original.params, apiConfig.options));
-            }
-
-            if (Object.prototype.hasOwnProperty.call(this.original, 'options')) {
-                Object.assign(this.options, _.pick(this.original.options, apiConfig.options));
-            }
-        }
-
-        this.options.context = this.original.context;
-
-        if (this.original.body && Object.keys(this.original.body).length) {
-            this.data = _.cloneDeep(this.original.body);
-        } else {
-            if (apiConfig.data) {
-                if (typeof apiConfig.data === 'function') {
-                    apiConfig.data = apiConfig.data(this);
-                }
-
-                if (Object.prototype.hasOwnProperty.call(this.original, 'query')) {
-                    Object.assign(this.data, _.pick(this.original.query, apiConfig.data));
-                }
-
-                if (Object.prototype.hasOwnProperty.call(this.original, 'params')) {
-                    Object.assign(this.data, _.pick(this.original.params, apiConfig.data));
-                }
-
-                if (Object.prototype.hasOwnProperty.call(this.original, 'options')) {
-                    Object.assign(this.data, _.pick(this.original.options, apiConfig.data));
-                }
-            }
-        }
-
-        this.user = this.original.user;
-        this.file = this.original.file;
-        this.files = this.original.files;
-
-        debug('original', this.original);
-        debug('options', this.options);
-        debug('data', this.data);
-    }
-}
-
-module.exports = Frame;

package/core/server/api/shared/headers.js

@@ -1,152 +0,0 @@
-const url = require('url');
-const debug = require('@tryghost/debug')('api:shared:headers');
-const Promise = require('bluebird');
-const INVALIDATE_ALL = '/*';
-
-const cacheInvalidate = (result, options = {}) => {
-    let value = options.value;
-
-    return {
-        'X-Cache-Invalidate': value || INVALIDATE_ALL
-    };
-};
-
-const disposition = {
-    /**
-     * @description Generate CSV header.
-     *
-     * @param {Object} result - API response
-     * @param {Object} options
-     * @return {Object}
-     */
-    csv(result, options = {}) {
-        let value = options.value;
-
-        if (typeof options.value === 'function') {
-            value = options.value();
-        }
-
-        return {
-            'Content-Disposition': `Attachment; filename="${value}"`,
-            'Content-Type': 'text/csv'
-        };
-    },
-
-    /**
-     * @description Generate JSON header.
-     *
-     * @param {Object} result - API response
-     * @param {Object} options
-     * @return {Object}
-     */
-    json(result, options = {}) {
-        return {
-            'Content-Disposition': `Attachment; filename="${options.value}"`,
-            'Content-Type': 'application/json',
-            'Content-Length': Buffer.byteLength(JSON.stringify(result))
-        };
-    },
-
-    /**
-     * @description Generate YAML header.
-     *
-     * @param {Object} result - API response
-     * @param {Object} options
-     * @return {Object}
-     */
-    yaml(result, options = {}) {
-        return {
-            'Content-Disposition': `Attachment; filename="${options.value}"`,
-            'Content-Type': 'application/yaml',
-            'Content-Length': Buffer.byteLength(JSON.stringify(result))
-        };
-    },
-
-    /**
-     * @description Content Disposition Header
-     *
-     * Create a header that invokes the 'Save As' dialog in the browser when exporting the database to file. The 'filename'
-     * parameter is governed by [RFC6266](http://tools.ietf.org/html/rfc6266#section-4.3).
-     *
-     * For encoding whitespace and non-ISO-8859-1 characters, you MUST use the "filename*=" attribute, NOT "filename=".
-     * Ideally, both. Examples: http://tools.ietf.org/html/rfc6266#section-5
-     *
-     * We'll use ISO-8859-1 characters here to keep it simple.
-     *
-     * @see http://tools.ietf.org/html/rfc598
-     */
-    file(result, options = {}) {
-        return Promise.resolve()
-            .then(() => {
-                let value = options.value;
-
-                if (typeof options.value === 'function') {
-                    value = options.value();
-                }
-
-                return value;
-            })
-            .then((filename) => {
-                return {
-                    'Content-Disposition': `Attachment; filename="${filename}"`
-                };
-            });
-    }
-};
-
-module.exports = {
-    /**
-     * @description Get header based on ctrl configuration.
-     *
-     * @param {Object} result - API response
-     * @param {Object} apiConfigHeaders
-     * @param {Object} frame
-     * @return {Promise}
-     */
-    async get(result, apiConfigHeaders = {}, frame) {
-        let headers = {};
-
-        if (apiConfigHeaders.disposition) {
-            const dispositionHeader = await disposition[apiConfigHeaders.disposition.type](result, apiConfigHeaders.disposition);
-
-            if (dispositionHeader) {
-                Object.assign(headers, dispositionHeader);
-            }
-        }
-
-        if (apiConfigHeaders.cacheInvalidate) {
-            const cacheInvalidationHeader = cacheInvalidate(result, apiConfigHeaders.cacheInvalidate);
-
-            if (cacheInvalidationHeader) {
-                Object.assign(headers, cacheInvalidationHeader);
-            }
-        }
-
-        const locationHeaderDisabled = apiConfigHeaders && apiConfigHeaders.location === false;
-        const hasFrameData = frame
-            && (frame.method === 'add')
-            && result[frame.docName]
-            && result[frame.docName][0]
-            && result[frame.docName][0].id;
-
-        if (!locationHeaderDisabled && hasFrameData) {
-            const protocol = (frame.original.url.secure === false) ? 'http://' : 'https://';
-            const resourceId = result[frame.docName][0].id;
-
-            let locationURL = url.resolve(`${protocol}${frame.original.url.host}`,frame.original.url.pathname);
-            if (!locationURL.endsWith('/')) {
-                locationURL += '/';
-            }
-            locationURL += `${resourceId}/`;
-
-            const locationHeader = {
-                Location: locationURL
-            };
-
-            Object.assign(headers, locationHeader);
-        }
-
-        debug(headers);
-        return headers;
-    }
-};

package/core/server/api/shared/http.js

@@ -1,127 +0,0 @@
-const url = require('url');
-const debug = require('@tryghost/debug')('api:shared:http');
-const shared = require('../shared');
-const models = require('../../models');
-
-/**
- * @description HTTP wrapper.
- *
- * This wrapper is used in the routes definition (see web/).
- * The wrapper receives the express request, prepares the frame and forwards the request to the pipeline.
- *
- * @param {Function} apiImpl - Pipeline wrapper, which executes the target ctrl function.
- * @return {Function}
- */
-const http = (apiImpl) => {
-    return async (req, res, next) => {
-        debug(`External API request to ${req.url}`);
-        let apiKey = null;
-        let integration = null;
-        let user = null;
-
-        if (req.api_key) {
-            apiKey = {
-                id: req.api_key.get('id'),
-                type: req.api_key.get('type')
-            };
-            integration = {
-                id: req.api_key.get('integration_id')
-            };
-        }
-
-        // NOTE: "external user" is only used in the subscriber app. External user is ID "0".
-        if ((req.user && req.user.id) || (req.user && models.User.isExternalUser(req.user.id))) {
-            user = req.user.id;
-        }
-
-        const frame = new shared.Frame({
-            body: req.body,
-            file: req.file,
-            files: req.files,
-            query: req.query,
-            params: req.params,
-            user: req.user,
-            session: req.session,
-            url: {
-                host: req.vhost ? req.vhost.host : req.get('host'),
-                pathname: url.parse(req.originalUrl || req.url).pathname,
-                secure: req.secure
-            },
-            context: {
-                api_key: apiKey,
-                user: user,
-                integration: integration,
-                member: (req.member || null)
-            }
-        });
-
-        frame.configure({
-            options: apiImpl.options,
-            data: apiImpl.data
-        });
-
-        try {
-            const result = await apiImpl(frame);
-
-            debug(`External API request to ${frame.docName}.${frame.method}`);
-            const headers = await shared.headers.get(result, apiImpl.headers, frame) || {};
-
-            // CASE: api ctrl wants to handle the express response (e.g. streams)
-            if (typeof result === 'function') {
-                debug('ctrl function call');
-                return result(req, res, next);
-            }
-
-            let statusCode = 200;
-            if (typeof apiImpl.statusCode === 'function') {
-                statusCode = apiImpl.statusCode(result);
-            } else if (apiImpl.statusCode) {
-                statusCode = apiImpl.statusCode;
-            }
-
-            res.status(statusCode);
-
-            // CASE: generate headers based on the api ctrl configuration
-            res.set(headers);
-
-            const send = (format) => {
-                if (format === 'plain') {
-                    debug('plain text response');
-                    return res.send(result);
-                }
-
-                debug('json response');
-                res.json(result || {});
-            };
-
-            let responseFormat;
-
-            if (apiImpl.response){
-                if (typeof apiImpl.response.format === 'function') {
-                    const apiResponseFormat = apiImpl.response.format();
-
-                    if (apiResponseFormat.then) { // is promise
-                        return apiResponseFormat.then((formatName) => {
-                            send(formatName);
-                        });
-                    } else {
-                        responseFormat = apiResponseFormat;
-                    }
-                } else {
-                    responseFormat = apiImpl.response.format;
-                }
-            }
-
-            send(responseFormat);
-        } catch (err) {
-            req.frameOptions = {
-                docName: frame.docName,
-                method: frame.method
-            };
-
-            next(err);
-        }
-    };
-};
-
-module.exports = http;

package/core/server/api/shared/index.js

@@ -1,25 +0,0 @@
-module.exports = {
-    get headers() {
-        return require('./headers');
-    },
-
-    get http() {
-        return require('./http');
-    },
-
-    get Frame() {
-        return require('./frame');
-    },
-
-    get pipeline() {
-        return require('./pipeline');
-    },
-
-    get validators() {
-        return require('./validators');
-    },
-
-    get serializers() {
-        return require('./serializers');
-    }
-};