W3cubDocs

/Meteor 1.5

Methods

Documentation of Meteor's Method (Remote Procedure Call) API.

Methods are remote functions that Meteor clients can invoke with Meteor.call.

Anywhere
Meteor.methods(methods)
import { Meteor } from 'meteor/meteor' (ddp-server/livedata_server.js, line 1586)

Defines functions that can be invoked over the network by clients.

Arguments

methods Object

Dictionary whose keys are method names and values are functions.

Example:

Meteor.methods({
  foo(arg1, arg2) {
    check(arg1, String);
    check(arg2, [Number]);

    // Do stuff...


    if (/* you want to throw an error */) {
      throw new Meteor.Error('pants-not-found', "Can't find my pants");
    }

    return 'some return value';
  },

  bar() {
    // Do other stuff...

    return 'baz';
  }
});

Calling methods on the server defines functions that can be called remotely by clients. They should return an EJSON-able value or throw an exception. Inside your method invocation, this is bound to a method invocation object, which provides the following:

  • isSimulation: a boolean value, true if this invocation is a stub.
  • unblock: when called, allows the next method from this client to begin running.
  • userId: the id of the current user.
  • setUserId: a function that associates the current client with a user.
  • connection: on the server, the connection this method call was received on.

Calling methods on the client defines stub functions associated with server methods of the same name. You don’t have to define a stub for your method if you don’t want to. In that case, method calls are just like remote procedure calls in other systems, and you’ll have to wait for the results from the server.

If you do define a stub, when a client invokes a server method it will also run its stub in parallel. On the client, the return value of a stub is ignored. Stubs are run for their side-effects: they are intended to simulate the result of what the server’s method will do, but without waiting for the round trip delay. If a stub throws an exception it will be logged to the console.

You use methods all the time, because the database mutators (insert, update, remove) are implemented as methods. When you call any of these functions on the client, you’re invoking their stub version that update the local cache, and sending the same write request to the server. When the server responds, the client updates the local cache with the writes that actually occurred on the server.

You don’t have to put all your method definitions into a single Meteor.methods call; you may call it multiple times, as long as each method has a unique name.

If a client calls a method and is disconnected before it receives a response, it will re-call the method when it reconnects. This means that a client may call a method multiple times when it only means to call it once. If this behavior is problematic for your method, consider attaching a unique ID to each method call on the client, and checking on the server whether a call with this ID has already been made. Alternatively, you can use Meteor.apply with the noRetry option set to true.

Read more about methods and how to use them in the Methods article in the Meteor Guide.

Anywhere
this.userId

The id of the user that made this method call, or null if no user was logged in.

The user id is an arbitrary string — typically the id of the user record in the database. You can set it with the setUserId function. If you’re using the Meteor accounts system then this is handled for you.

Server
this.setUserId(userId)

Set the logged in user.

Arguments

userId String or null

The value that should be returned by userId on this connection.

Call this function to change the currently logged-in user on the connection that made this method call. This simply sets the value of userId for future method calls received on this connection. Pass null to log out the connection.

If you are using the built-in Meteor accounts system then this should correspond to the _id field of a document in the Meteor.users collection.

setUserId is not retroactive. It affects the current method call and any future method calls on the connection. Any previous method calls on this connection will still see the value of userId that was in effect when they started.

If you also want to change the logged-in user on the client, then after calling setUserId on the server, call Meteor.connection.setUserId(userId) on the client.

Anywhere
this.isSimulation

Access inside a method invocation. Boolean value, true if this invocation is a stub.

Server
this.unblock()

Call inside a method invocation. Allow subsequent method from this client to begin running in a new fiber.

On the server, methods from a given client run one at a time. The N+1th invocation from a client won’t start until the Nth invocation returns. However, you can change this by calling this.unblock. This will allow the N+1th invocation to start running in a new fiber.

Server
this.connection

Access inside a method invocation. The connection that this method was received on. null if the method is not associated with a connection, eg. a server initiated method call. Calls to methods made from a server method which was in turn initiated from the client share the same connection.

Anywhere
new Meteor.Error(error, [reason], [details])
import { Meteor } from 'meteor/meteor' (meteor/errors.js, line 71)

This class represents a symbolic error thrown by a method.

Arguments

error String

A string code uniquely identifying this kind of error. This string should be used by callers of the method to determine the appropriate action to take, instead of attempting to parse the reason or details fields. For example:

// on the server, pick a code unique to this error
// the reason field should be a useful debug message
throw new Meteor.Error("logged-out",
  "The user must be logged in to post a comment.");

// on the client
Meteor.call("methodName", function (error) {
  // identify the error
  if (error && error.error === "logged-out") {
    // show a nice error message
    Session.set("errorMessage", "Please log in to post a comment.");
  }
});

For legacy reasons, some built-in Meteor functions such as check throw errors with a number in this field.

reason String

Optional. A short human-readable summary of the error, like 'Not Found'.

details String

Optional. Additional information about the error, like a textual stack trace.

If you want to return an error from a method, throw an exception. Methods can throw any kind of exception. But Meteor.Error is the only kind of error that a server will send to the client. If a method function throws a different exception, then it will be mapped to a sanitized version on the wire. Specifically, if the sanitizedError field on the thrown error is set to a Meteor.Error, then that error will be sent to the client. Otherwise, if no sanitized version is available, the client gets Meteor.Error(500, 'Internal server error').

Anywhere
Meteor.call(name, [arg1, arg2...], [asyncCallback])
import { Meteor } from 'meteor/meteor' (ddp-client/livedata_connection.js, line 724)

Invokes a method passing any number of arguments.

Arguments

name String

Name of method to invoke

arg1, arg2... EJSON-able Object

Optional method arguments

asyncCallback Function

Optional callback, which is called asynchronously with the error or result after the method is complete. If not provided, the method runs synchronously if possible (see below).

This is how to invoke a method. It will run the method on the server. If a stub is available, it will also run the stub on the client. (See also Meteor.apply, which is identical to Meteor.call except that you specify the parameters as an array instead of as separate arguments and you can specify a few options controlling how the method is executed.)

If you include a callback function as the last argument (which can’t be an argument to the method, since functions aren’t serializable), the method will run asynchronously: it will return nothing in particular and will not throw an exception. When the method is complete (which may or may not happen before Meteor.call returns), the callback will be called with two arguments: error and result. If an error was thrown, then error will be the exception object. Otherwise, error will be undefined and the return value (possibly undefined) will be in result.

// Asynchronous call
Meteor.call('foo', 1, 2, (error, result) => { ... });

If you do not pass a callback on the server, the method invocation will block until the method is complete. It will eventually return the return value of the method, or it will throw an exception if the method threw an exception. (Possibly mapped to 500 Server Error if the exception happened remotely and it was not a Meteor.Error exception.)

// Synchronous call

const result = Meteor.call('foo', 1, 2);

On the client, if you do not pass a callback and you are not inside a stub, call will return undefined, and you will have no way to get the return value of the method. That is because the client doesn’t have fibers, so there is not actually any way it can block on the remote execution of a method.

Finally, if you are inside a stub on the client and call another method, the other method is not executed (no RPC is generated, nothing “real” happens). If that other method has a stub, that stub stands in for the method and is executed. The method call’s return value is the return value of the stub function. The client has no problem executing a stub synchronously, and that is why it’s okay for the client to use the synchronous Meteor.call form from inside a method body, as described earlier.

Meteor tracks the database writes performed by methods, both on the client and the server, and does not invoke asyncCallback until all of the server’s writes replace the stub’s writes in the local cache. In some cases, there can be a lag between the method’s return value being available and the writes being visible: for example, if another method still outstanding wrote to the same document, the local cache may not be up to date until the other method finishes as well. If you want to process the method’s result as soon as it arrives from the server, even if the method’s writes are not available yet, you can specify an onResultReceived callback to Meteor.apply.

Anywhere
Meteor.apply(name, args, [options], [asyncCallback])
import { Meteor } from 'meteor/meteor' (ddp-client/livedata_connection.js, line 768)

Invoke a method passing an array of arguments.

Arguments

name String

Name of method to invoke

args Array of EJSON-able Objects

Method arguments

asyncCallback Function

Optional callback; same semantics as in Meteor.call.

Options

wait Boolean

(Client only) If true, don't send this method until all previous method calls have completed, and don't send any subsequent method calls until this one is completed.

onResultReceived Function

(Client only) This callback is invoked with the error or result of the method (just like asyncCallback) as soon as the error or result is available. The local cache may not yet reflect the writes performed by the method.

noRetry Boolean

(Client only) if true, don't send this method again on reload, simply call the callback an error with the error code 'invocation-failed'.

throwStubExceptions Boolean

(Client only) If true, exceptions thrown by method stubs will be thrown instead of logged, and the method will not be invoked on the server.

Meteor.apply is just like Meteor.call, except that the method arguments are passed as an array rather than directly as arguments, and you can specify options about how the client executes the method.

DDPRateLimiter

Customize rate limiting for methods and subscriptions.

By default, DDPRateLimiter is configured with a single rule. This rule limits login attempts, new user creation, and password resets to 5 attempts every 10 seconds per connection. It can be removed by calling Accounts.removeDefaultRateLimit().

To use DDPRateLimiter for modifying the default rate-limiting rules, add the ddp-rate-limiter package to your project in your terminal:

meteor add ddp-rate-limiter

Server
DDPRateLimiter.addRule(matcher, numRequests, timeInterval, callback)
import { DDPRateLimiter } from 'meteor/ddp-rate-limiter' (ddp-rate-limiter/ddp-rate-limiter.js, line 70)

Add a rule that matches against a stream of events describing method or subscription attempts. Each event is an object with the following properties:

  • type: Either "method" or "subscription"
  • name: The name of the method or subscription being called
  • userId: The user ID attempting the method or subscription
  • connectionId: A string representing the user's DDP connection
  • clientAddress: The IP address of the user

Returns unique ruleId that can be passed to removeRule.

Arguments

matcher Object

Matchers specify which events are counted towards a rate limit. A matcher is an object that has a subset of the same properties as the event objects described above. Each value in a matcher object is one of the following:

  • a string: for the event to satisfy the matcher, this value must be equal to the value of the same property in the event object

  • a function: for the event to satisfy the matcher, the function must evaluate to true when passed the value of the same property in the event object

Here's how events are counted: Each event that satisfies the matcher's filter is mapped to a bucket. Buckets are uniquely determined by the event object's values for all properties present in both the matcher and event objects.

numRequests number

number of requests allowed per time interval. Default = 10.

timeInterval number

time interval in milliseconds after which rule's counters are reset. Default = 1000.

callback Function

function to be called after a rule is executed.

Custom rules can be added by calling DDPRateLimiter.addRule. The rate limiter is called on every method and subscription invocation.

A rate limit is reached when a bucket has surpassed the rule’s predefined capactiy, at which point errors will be returned for that input until the buckets are reset. Buckets are regularly reset after the end of a time interval.

Here’s example of defining a rule and adding it into the DDPRateLimiter:

// Define a rule that matches login attempts by non-admin users.

const loginRule = {
  userId(userId) {
    const user = Meteor.users.findOne(userId);
    return user && user.type !== 'admin';
  },

  type: 'method',
  name: 'login'

};

// Add the rule, allowing up to 5 messages every 1000 milliseconds.
DDPRateLimiter.addRule(loginRule, 5, 1000);

Server
DDPRateLimiter.removeRule(id)
import { DDPRateLimiter } from 'meteor/ddp-rate-limiter' (ddp-rate-limiter/ddp-rate-limiter.js, line 85)

Removes the specified rule from the rate limiter. If rule had hit a rate limit, that limit is removed as well.

Arguments

id string

'ruleId' returned from addRule

Server
DDPRateLimiter.setErrorMessage(message)
import { DDPRateLimiter } from 'meteor/ddp-rate-limiter' (ddp-rate-limiter/ddp-rate-limiter.js, line 28)

Set error message text when method or subscription rate limit exceeded.

Arguments

message string or Function

Functions are passed in an object with a timeToReset field that specifies the number of milliseconds until the next method or subscription is allowed to run. The function must return a string of the error message.

© 2011–2017 Meteor Development Group, Inc.
Licensed under the MIT License.
https://docs.meteor.com/api/methods.html