cfs:http-methods

Add server-side methods to the HTTP object your app. It's a server-side package only - no client simulations added.

Usage

The HTTP object gets a methods method:

  HTTP.methods({
    'list': function() {
      return '<b>Default content type is text/html</b>';
    }
  });

Methods scope

The methods scope contains different kinds of inputs. We can also get user details if logged in.

• this.userId - the user whose id and token was used to run this method, if set/found
• this.method - GET, POST, PUT, DELETE
• this.query - query params ?token=1&id=2 -> { token: 1, id: 2 }
• this.params - set params /foo/:name/test/:id -> { name: '', id: '' }
• this.userAgent - get the user agent string set in the request header
• this.requestHeaders - request headers object
• this.setUserId(id) - option for setting the this.userId
• this.isSimulation - always false on the server
• this.unblock - not implemented
• this.setContentType('text/html') - set the content type in header, defaults to text/html
• this.addHeader('Content-Disposition', 'attachment; filename="name.ext"')
• this.setStatusCode(200) - set the status code in the response header
• createReadStream - if a request, then get the read stream
• createWriteStream - if you want to stream data to the client
• Error - when streaming we have to be able to send error and close connection
• this.request The original request object

Passing data via header

From the client:

  HTTP.post('list', {
    data: { foo: 'bar' }
  }, function(err, result) {
    console.log('Content: ' + result.content + ' === "Hello"');
  });

HTTP Server method:

  HTTP.methods({
    'list': function(data) {
      if (data.foo === 'bar') {
        /* data we pass via the header is parsed by EJSON.parse
        If not able, then it returns the raw data instead */
      }
      return 'Hello';
    }
  });

Parameters

The method name or URL can be used to pass parameters to the method. The parameters are available on the server under this.params:

Client

  HTTP.post('/items/12/emails/5', function(err, result) {
    console.log('Got back: ' + result.content);
  });

Server

  HTTP.methods({
    '/items/:itemId/emails/:emailId': function() {
      // this.params.itemId === '12'
      // this.params.emailId === '5'
    }
  });

Extended usage

The HTTP.methods normally takes a function, but it can be set to an object for fine-grained handling.

Example:

  HTTP.methods({
    '/hello': {
      get: function(data) {},
      // post: function(data) {},
      // put: function(data) {},
      // delete: function(data) {},
      // options: function() {
      //   // Example of a simple options function
      //   this.setStatusCode(200);
      //   this.addHeader('Accept', 'POST,PUT');
      //    // The options for this restpoint
      //    var options = {
      //      POST: {
      //        description: 'Create an issue',
      //        parameters: {
      //          title: {
      //            type: 'string',
      //            description: 'Issue title'
      //          }
      //        }
      //       }
      //    };
      //    // Print the options in pretty json
      //    return JSON.stringify(options, null, '\t');
      //  },
      //  stream: true // flag whether to allow stream handling in the request
    }
  });

In this example the mounted http rest point will only support the get method

Example:

  HTTP.methods({
    '/hello': {
      method: function(data) {},
    }
  });

In this example all methods get, put, post, delete will use the same function - This would be equal to setting the function directly on the http mount point

Authentication

The client needs the access_token to login in HTTP methods. One could create a HTTP login/logout method for allowing pure external access

Client

  HTTP.post('/hello', {
    params: {
      token: Accounts && Accounts._storedLoginToken()
    }
  }, function(err, result) {
    console.log('Got back: ' + result.content);
  });

Server

  'hello': function(data) {
    if (this.userId) {
      var user = Meteor.users.findOne({ _id: this.userId });
      return 'Hello ' + (user && user.username || user && user.emails[0].address || 'user');
    } else {
      this.setStatusCode(401); // Unauthorized
    }
  }

Using custom authentication

It's possible to make your own function to set the userId - not using the built-in token pattern.

  // My auth will return the userId
  var myAuth = function() {
    // Read the token from '/hello?token=5'
    var userToken = self.query.token;
    // Check the userToken before adding it to the db query
    // Set the this.userId
    if (userToken) {
      var user = Meteor.users.findOne({ 'services.resume.loginTokens.token': userToken });

      // Set the userId in the scope
      return user && user._id;
    }  
  };

  HTTP.methods({
    '/hello': {
      auth: myAuth,
      method: function(data) {
        // this.userId is set by myAuth
        if (this.userId) { /**/ } else { /**/ }
      }
    }
  });

The above resembles the builtin auth handler

Security

When buffering data instead of streaming we set the buffer limit to 5mb - This can be changed on the fly:

  // Set the max data length
  // 5mb = 5 * 1024 * 1024 = 5242880;
  HTTP.methodsMaxDataLength = 5242880;

Login and logout (TODO)

These operations are not currently supported for off Meteor use - there are some security considerations.

basic-auth is broadly supported, but:

• password should not be sent in clear text - hash with base64?
• should be used on https connections
• Its difficult / impossible to logout a user?

token the current access_token seems to be a better solution. Better control and options to logout users. But calling the initial login method still requires:

• hashing of password
• use https

HTTP Client-side usage

If you want to use the HTTP client-side functionality and find yourself having a hard time viewing all available options; these can be found on https://docs.meteor.com/#/full/http.