From 46ed6fac9f94d300a23903a71cfafdb5c8b1ba91 Mon Sep 17 00:00:00 2001
From: Haoliang Gao <sakura9515@gmail.com>
Date: Fri, 20 Oct 2017 06:25:44 -0500
Subject: [PATCH] feat: add Subscription (#1469)

Ref https://github.com/eggjs/egg/issues/1468
---
 docs/source/en/basics/objects.md    | 18 ++++++++++++++++++
 docs/source/zh-cn/basics/objects.md | 18 ++++++++++++++++++
 index.js                            |  8 +++++++-
 test/index.test.js                  |  1 +
 test/lib/egg.test.js                |  2 ++
 5 files changed, 46 insertions(+), 1 deletion(-)

diff --git a/docs/source/en/basics/objects.md b/docs/source/en/basics/objects.md
index bbe71048e6..23c0361253 100644
--- a/docs/source/en/basics/objects.md
+++ b/docs/source/en/basics/objects.md
@@ -270,6 +270,24 @@ We can get it via `ctx.coreLogger`, the difference between the Context Logger is
 
 We can get them via `this.logger` in Controller and Service instance, they are essentially a Context Logger, but additional file path will be added to logs, easy to locate the log print location.
 
+## Subscription
+
+Subscription is the model for subscribing, including consumer in message broker or schedule.
+
+The base class of Subscription is exported by egg.
+
+```js
+const Subscription = require('egg').Subscription;
+
+class Schedule extends Subscription {
+  // This method should be implemented
+  // subscribe can be generator function or async function
+  * subscribe() {}
+}
+```
+
+We recommend plugin developers to implement based on this model, For example, [Schedule](./schedule.md).
+
 [Koa]: http://koajs.com
 [Koa.Application]: http://koajs.com/#application
 [Koa.Context]: http://koajs.com/#context
diff --git a/docs/source/zh-cn/basics/objects.md b/docs/source/zh-cn/basics/objects.md
index eec9fcb3a9..65598ff0e8 100644
--- a/docs/source/zh-cn/basics/objects.md
+++ b/docs/source/zh-cn/basics/objects.md
@@ -270,6 +270,24 @@ module.exports = {
 
 我们可以在 Controller 和 Service 实例上通过 `this.logger` 获取到它们，它们本质上就是一个 Context Logger，不过在打印日志的时候还会额外的加上文件路径，方便定位日志的打印位置。
 
+## Subscription
+
+订阅模型是一种比较常见的开发模式，譬如消息中间件的消费者或调度任务。因此我们提供了 Subscription 基类来规范化这个模式。
+
+可以通过以下方式来引用 Subscription 基类：
+
+```js
+const Subscription = require('egg').Subscription;
+
+class Schedule extends Subscription {
+  // 需要实现此方法
+  // subscribe 可以为 generator function 或 async function
+  * subscribe() {}
+}
+```
+
+插件开发者可以根据自己的需求基于它定制订阅规范，如[定时任务](./schedule.md)就是使用这种规范实现的。
+
 [Koa]: http://koajs.com
 [Koa.Application]: http://koajs.com/#application
 [Koa.Context]: http://koajs.com/#context
diff --git a/index.js b/index.js
index 32fdbac8da..651c446343 100644
--- a/index.js
+++ b/index.js
@@ -47,7 +47,13 @@ exports.Controller = require('./lib/core/base_context_class');
 exports.Service = require('./lib/core/base_context_class');
 
 /**
- * @member {Service} Egg#BaseContextClass
+ * @member {Subscription} Egg#Subscription
+ * @since 1.10.0
+ */
+exports.Subscription = require('./lib/core/base_context_class');
+
+/**
+ * @member {BaseContextClass} Egg#BaseContextClass
  * @since 1.2.0
  */
 exports.BaseContextClass = require('./lib/core/base_context_class');
diff --git a/test/index.test.js b/test/index.test.js
index 44a3de9470..1a76149d09 100644
--- a/test/index.test.js
+++ b/test/index.test.js
@@ -13,6 +13,7 @@ describe('test/index.test.js', () => {
       'BaseContextClass',
       'Controller',
       'Service',
+      'Subscription',
       'startCluster',
     ]);
   });
diff --git a/test/lib/egg.test.js b/test/lib/egg.test.js
index 6fecf52206..a7146c4166 100644
--- a/test/lib/egg.test.js
+++ b/test/lib/egg.test.js
@@ -223,6 +223,8 @@ describe('test/lib/egg.test.js', () => {
         .expect('hello')
         .expect(200);
 
+      yield sleep(1000);
+
       const logPath = path.join(utils.getFilepath('apps/base-context-class'), 'logs/base-context-class/base-context-class-web.log');
       const log = fs.readFileSync(logPath, 'utf8');
       assert(log.match(/INFO .*? \[service\.home\] appname: base-context-class/));