Update README.md

1 files changed, 132 insertions, 0 deletions

diff --git a/README.md b/README.md
index 74a2d24c..c236cb5e 100644
--- a/README.md
+++ b/README.md
@@ -175,6 +175,138 @@ $ rr http:workers -i
 +---------+-----------+---------+---------+--------------------+
 ```
 
+Writing services:
+--------
+RoadRunner uses service bus to organize it's internal services and their depencies, this approach is similar to PHP Container implementation. You can create your own services, event listeners, middlewares and etc.
+
+RoadRunner would not start service without a proper config section at the moment, simply add new section to .rr file.
+
+```yaml
+service:
+  enable: true
+  option: value
+```
+
+You can write your own config file now:
+
+```golang
+package service
+
+type config struct {
+	Enable bool
+	Option string
+}
+```
+
+To create the service implement interface:
+
+```golang
+// Service provides high level functionality for road runner modules.
+type Service interface {
+	// Init must return configure service and return true if service hasStatus enabled. Must return error in case of
+	// misconfiguration. Services must not be used without proper configuration pushed first.
+	Init(cfg Config, c Container) (enabled bool, err error)
+
+	// Serve serves.
+	Serve() error
+
+	// Stop stops the service.
+	Stop()
+}
+```
+
+Simple service might look like:
+
+```golang
+package service
+
+import (
+	"github.com/spiral/roadrunner/service"
+)
+
+const ID = "service"
+
+type Service struct {
+	cfg  *config
+}
+
+
+func (s *Service) Init(cfg service.Config, reg service.Container) (enabled bool, err error) {
+	config := &config{}
+	if err := cfg.Unmarshal(config); err != nil {
+		return false, err
+	}
+
+	if !config.Enable {
+		return false, nil
+	}
+
+	s.cfg = config
+	return true, nil
+}
+
+func (s *Service) Serve() error {
+	return nil
+}
+
+func (s *Service) Stop() {
+	 // nothing
+}
+```
+
+Service can be added to RR bus by creating your own version of [main.go](https://github.com/spiral/roadrunner/blob/master/cmd/rr/main.go) file:
+
+
+```golang
+rr.Container.Register(service.ID, &service.Service{})
+```
+
+Your service should work now. In addition you create your own RPC adaptes which are available from commands and PHP using Goridge:
+
+```golang
+// in Init() method
+if r, ok := c.Get(rpc.ID); ok >= service.StatusConfigured {
+		if h, ok := r.(*rpc.Service); ok {
+			h.Register("service", &rpcServer{s})
+		}
+}
+```
+
+> RPC server must be written based on net/rpc rules: https://golang.org/pkg/net/rpc/
+
+Now, you can connect to this service from PHP:
+
+```php
+// make sure to use same port as in .rr config for RPC service
+$rpc = new Spiral\Goridge\RPC(new Spiral\Goridge\SocketRelay('localhost', 6001));
+
+print_r($rpc->call('service.Method', $ars));
+```
+
+HTTP service provides it's own methods as well:
+
+```php
+print_r($rpc->call('http.Workers', true));
+//print_r($rpc->call('http.Reset', true));
+```
+
+You can register http middleware or event listener using such approach:
+
+```golang
+import (
+  rrttp "github.com/spiral/roadrunner/service/http"
+)
+
+//...
+
+if h, ok := c.Get(rrttp.ID); ok >= service.StatusConfigured {
+		if h, ok := h.(*rrttp.Service); ok {
+			h.AddMiddleware(s.middleware)
+      h.AddListener(s.middleware)
+		}
+	}
+```
+
 Standalone Usage:
 --------
 You can also use RoadRunner as library in order to drive your application without any additional protocol at top of it.