{"id":13436188,"url":"https://github.com/opensaasstudio/plasma","last_synced_at":"2025-03-18T20:31:01.215Z","repository":{"id":143705849,"uuid":"85933423","full_name":"opensaasstudio/plasma","owner":"opensaasstudio","description":"universal server push middleware by using gRPC stream and Server Sent Events(SSE)","archived":true,"fork":false,"pushed_at":"2019-08-15T10:57:23.000Z","size":231,"stargazers_count":162,"open_issues_count":7,"forks_count":11,"subscribers_count":15,"default_branch":"master","last_synced_at":"2024-11-28T13:17:15.959Z","etag":null,"topics":["eventsource","go","grpc","grpc-stream","middleware","serverpush"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/opensaasstudio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-03-23T09:52:14.000Z","updated_at":"2024-08-07T05:17:17.000Z","dependencies_parsed_at":"2023-06-18T04:31:07.862Z","dependency_job_id":null,"html_url":"https://github.com/opensaasstudio/plasma","commit_stats":null,"previous_names":["openfresh/plasma"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensaasstudio%2Fplasma","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensaasstudio%2Fplasma/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensaasstudio%2Fplasma/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/opensaasstudio%2Fplasma/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/opensaasstudio","download_url":"https://codeload.github.com/opensaasstudio/plasma/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244301345,"owners_count":20430925,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["eventsource","go","grpc","grpc-stream","middleware","serverpush"],"created_at":"2024-07-31T03:00:45.223Z","updated_at":"2025-03-18T20:31:00.802Z","avatar_url":"https://github.com/opensaasstudio.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"plasma\n==========\n\n[![Circle CI](https://circleci.com/gh/openfresh/plasma.svg?style=shield\u0026circle-token=8e3162c9a55b29a5fa0488834225a84c013977b1)](https://circleci.com/gh/openfresh/plasma)\n[![Language](https://img.shields.io/badge/language-go-brightgreen.svg?style=flat)](https://golang.org/)\n[![issues](https://img.shields.io/github/issues/openfresh/plasma.svg?style=flat)](https://github.com/openfresh/plasma/issues?state=open)\n[![License: MIT](https://img.shields.io/badge/license-MIT-orange.svg)](LICENSE)\n[![imagelayers.io](https://badge.imagelayers.io/openfresh/plasma:latest.svg)](https://imagelayers.io/?images=openfresh/plasma:latest 'Get your own badge on imagelayers.io')\n[![Docker Stars](https://img.shields.io/docker/stars/openfresh/plasma.svg)]()\n[![Docker Pulls](https://img.shields.io/docker/pulls/openfresh/plasma.svg)]()\n\n**Attention: This repository was transfererd from [openfresh](https://github.com/openfresh).**\n\n![logo](img/plasma_logo.png)\n\nplasma is event push middleware by using gRPC stream.\n\n## Description\n\nPlasma is middleware for sending event specialized for a stream. Plasma provides EventSource and gRPC Stream from the same endpoint.\n\n![img](img/plasma_diagram.png)\n\n## Installation\n\nThis middleware requires Redis.\n\n### From Source\n\n```bash\n$ git clone git://github.com/openfresh/plasma.git $GOPATH/src/github.com/openfresh/plasma\n$ cd  $GOPATH/src/github.com/openfresh/plasma\n$ make deps\n$ make build\n```\n\nThe binary is generated under the `bin/` directory.\n\n### Using docker\n\nYou can also use the Docker image.\n\n```bash\n$ docker run -p 8080:8080 -p 50051:50051 -p 9999:9999 openfresh/plasma\n```\n\n### Using docker-compose\n\nYou can use docker-compose for easy use without preparing Redis.\n\n```bash\n$ git clone git://github.com/openfresh/plasma.git $GOPATH/src/github.com/openfresh/plasma\n$ cd  $GOPATH/src/github.com/openfresh/plasma\n$ docker-compose up -d\n```\n\n# Usage Subscriber\n\n## Server Sent Events\n\n[Using server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events)\n\nYour can use SSE if you request with `Accept:text-stream` header.\n\nYou request events that you want to subscribe to this endpoint. You can specify multiple events separated by commas.\nThe query name can be set with the `EventQuery` environment variable．(default value of EventQuery is  `eventType` )．\n\nHere is a simple example using [Yaffle / EventSource] (https://github.com/Yaffle/EventSource).\n\n```javascript\n    var source = new EventSource('//localhost:8080/?eventType=program:1234:views,program:1234:poll,program:1234:annotation');\n    \n    source.addEventListener(\"open\", function(e) {\n        console.log(\"open\");\n    });\n    \n    source.addEventListener(\"error\", function(e) {\n        console.log(\"error\");\n    });\n    \n    source.addEventListener(\"message\", function(e) {\n        console.log(\"message event: \", e.data);\n    });\n```\n\nThe JSON schema of data returned from Plasma is as follows.\n\n```javascript\n{\n    \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n    \"id\": \"/events\",\n    \"properties\": {\n        \"data\": {\n            \"id\": \"/events/data\",\n            \"type\": \"string\"\n        },\n        \"meta\": {\n            \"id\": \"/events/meta\",\n            \"properties\": {\n                \"type\": {\n                    \"id\": \"/events/meta/type\",\n                    \"type\": \"string\"\n                }\n            },\n            \"type\": \"object\"\n        }\n    },\n    \"type\": \"object\"\n}\n```\n\nIf the `DEBUG` environment variable is enabled, you can access the debug endpoint.\n\n### GET /debug\n\nYou can publish events to Redis from this endpoint.  You need to enter valid JSON in EventData form.\n\n## gRPC Stream\n\nYou can subscribe to events using gRPC Stream.\n\nThe ProtocolBuffer file is [here](https://github.com/openfresh/plasma/blob/master/protobuf/stream.proto) .\n\nThe following is a simple Go sample.\n\n```go\nfunc main() {\n    conn, err := grpc.Dial(\"localhost:50051\", grpc.WithInsecure())\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer conn.Close()\n\n    client := proto.NewStreamServiceClient(conn)\n    ctx := context.Background()\n\n    req := proto.Request{\n        Events: []*proto.EventType{\n            eventType(\"program:1234:poll\"),\n            eventType(\"program:1234:views\"),\n        },\n    }\n\n    ss, err := client.Events(ctx)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // subscribe event\n    if err := ss.Send(\u0026req); err != nil {\n        log.Fatal(err)\n    }\n\n    for {\n        resp, err := ss.Recv()\n        if err != nil {\n            log.Println(err)\n            continue\n        }\n        if resp == nil {\n            log.Println(\"payload is nil\")\n            continue\n        }\n        fmt.Printf(\"Meta: %s\\tData: %s\\n\", resp.EventType.Type, resp.Data)\n    }\n}\n```\n\n### unsubscribe\n\n`Events` request is stream. If you unsubscribe event, set empty event data.\n\n```go\n    req := proto.Request{\n        // empty events\n        Events: []*proto.EventType{},\n    }\n\n    ss, err := client.Events(ctx)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    // unsubscribe event\n    if err := ss.Send(\u0026req); err != nil {\n        log.Fatal(err)\n    }\n```\n\n# Usage Publisher\n\nYou publish events to the channel that Plasma subscribes according to the following JSON Schema.\n\n```javascript\n{\n    \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n    \"id\": \"/events\",\n    \"properties\": {\n        \"data\": {\n            \"id\": \"/events/data\",\n            \"type\": \"string\"\n        },\n        \"meta\": {\n            \"id\": \"/events/meta\",\n            \"properties\": {\n                \"type\": {\n                    \"id\": \"/events/meta/type\",\n                    \"type\": \"string\"\n                }\n            },\n            \"type\": \"object\"\n        }\n    },\n    \"type\": \"object\"\n}\n```\n\n[openfresh/plasma-go](https://github.com/openfresh/plasma-go) is a library that wraps publish an event to Redis.\n\n## HealthCheck\n\n### GET /hc\n\nYou can do a health check. Check the status of Redis.\nIf there is a problem it returns 500, and if there is no problem it returns 200.\n\n## Metrics\n\n### GET /metrics/go\n\nYou can get golang metrics from this endpoint.\n\nThe following golang metrics can be taken.\n\n| name                | type      | desc                                                                  |\n|---------------------|-----------|-----------------------------------------------------------------------|\n| go_version          | string    | version of go                                                         |\n| go_os               | string    | os                                                                    |\n| go_arch             | string    | arch                                                                  |\n| cpu_num             | int       | number of cpus                                                        |\n| goroutine_num       | int       | number of goroutines                                                  |\n| gomaxprocs          | int       | number of operating system threads                                    |\n| cgo_call_num        | int64     | number of cgo calls                                                   |\n| memory_alloc        | uint64    | bytes of allocated heap objects                                       |\n| memory_total_alloc  | uint64    | cumulative bytes allocated for heap objects                           |\n| memory_sys          | uint64    | total bytes of memory                                                 |\n| memory_lookups      | uint64    | number of pointer                                                     |\n| memory_mallocs      | uint64    | cumulative count of heap objects allocated                            |\n| memory_frees        | uint64    | cumulative count of heap objects freed                                |\n| memory_stack        | uint64    | bytes in stack spans                                                  |\n| heap_alloc          | uint64    | bytes of allocated heap objects                                       |\n| heap_sys            | uint64    | bytes of heap memory obtained                                         |\n| heap_idle           | uint64    | bytes in idle spans                                                   |\n| heap_inuse          | uint64    | bytes in in-use spans                                                 |\n| heap_released       | uint64    | bytes of physical memory returned to the OS                           |\n| heap_objects        | uint64    | number of allocated heap objects                                      |\n| gc_next             | uint64    | target heap size of the next GC cycle                                 |\n| gc_last             | uint64    | time the last garbage collection finished, as, nanoseconds since 1970 |\n| gc_num              | uint32    | number of completed GC cycles                                         |\n| gc_per_second       | float64   | GC per second                                                         |\n| gc_pause_per_second | float64   | GC pause per second                                                   |\n| gc_pause            | []float64 | GC pause                                                              |\n\n\n### GET /metrics/plasma\n\nYou can get plasma metrics from this endpoint.\n\nThe following golang metrics can be taken.\n\n| name                | type      | desc                                                                  |\n|---------------------|-----------|-----------------------------------------------------------------------|\n| connections         | int64     | number of connected all clients                                           |\n| connections_sse         | int64     | number of connected SSE sclients                                           |\n| connections_grpc         | int64     | number of connected gRPC sclients                                           |\n\n## Config\n\n| name                                            | type          | desc                                                                                  | default           | note                                                                               |\n|-------------------------------------------------|---------------|---------------------------------------------------------------------------------------|-------------------|------------------------------------------------------------------------------------|\n| PLASMA_PORT                                     | string        | http(https) port number                                                               | 8080              |                                                                                    |\n| PLASMA_GRPC_PORT                                | string        | gRPC port number                                                                      | 50051             |                                                                                    |\n| PLASMA_METRICS_PORT                             | string        | metrics port number                                                                   | 9999              |                                                                                    |\n| PLASMA_PPROF_HOST                               | string        | pprof host                                                                            | 0.0.0.0           |                                                                                    |\n| PLASMA_PPROF_PORT                               | string        | pprof port number                                                                     | 6060              |                                                                                    |\n| PLASMA_DEBUG                                    | bool          | debug mode                                                                            | false             |                                                                                    |\n| PLASMA_ORIGIN                                   | string        | set to Access-Controll-Allow-Origin                                                   |                   |                                                                                    |\n| PLASMA_SSE_RETRY                                | int           | reconnect to the source milliseconds after each connection is closed                  | 2000              |                                                                                    |\n| PLASMA_SSE_EVENTQUERY                           | string        | use as a querystring in SSE                                                           | eventType         | ex) /?eventType=program:1234:views                                                 |\n| PLASMA_SUBSCRIBER_TYPE                          | string        | subscriber type                                                                       | mock              | support \"mock\" and \"redis\"                                                         |\n| PLASMA_SUBSCRIBER_REDIS_ADDR                    | string        | Redis address including port number                                                   | localhost:6379    |                                                                                    |\n| PLASMA_SUBSCRIBER_REDIS_PASSWORD                | string        | Redis password                                                                        |                   |                                                                                    |\n| PLASMA_SUBSCRIBER_REDIS_DB                      | int           | Redis DB                                                                              | 0                 |                                                                                    |\n| PLASMA_SUBSCRIBER_REDIS_CHANNELS                | string        | channels of Redis to subscribe (multiple specifications possible)                     |                   |                                                                                    |\n| PLASMA_SUBSCRIBER_REDIS_OVER_MAX_RETRY_BEHAVIOR | string        | Behavior of plasma when the number of retries connecting to Redis exceeds the maximum |                   | \"die\" or \"alive\"                                                                   |\n| PLASMA_SUBSCRIBER_REDIS_TIMEOUT                 | time.Duration | timeout for receive message from Redis                                                | 1s                |                                                                                    |\n| PLASMA_SUBSCRIBER_REDIS_RETRY_INTERVAL          | time.Duration | interval for retry to receive message from Redis                                      | 5s                |                                                                                    |\n| PLASMA_ERROR_LOG_OUT                            | string        | log file path                                                                         |                   | stdout, stderr, filepath                                                           |\n| PLASMA_ERROR_LOG_LEVEL                          | string        | log output level                                                                      |                   | panic,fatal,error,warn,info,debug                                                  |\n| PLASMA_ACCESS_LOG_OUT                           | string        | log file path                                                                         |                   | stdout, stderr, filepath                                                           |\n| PLASMA_ACCESS_LOG_LEVEL                         | string        | log output level                                                                      |                   | panic,fatal,error,warn,info,debug                                                  |\n| PLASMA_TLS_CERT_FILE                            | string        | cert file path                                                                        |                   | TLS is enabled only when you set both PLASMA_TLS_CERT_FILE and PLASMA_TLS_KEY_FILE |\n| PLASMA_TLS_KEY_FILE                             | string        | key file path                                                                         |                   |                                                                                    |\n| PLASMA_METRICS_TYPE                             | string        | metrics type                                                                          |                   | support \"log\" or \"syslog\". if this value is empty, metrics will be disabled        |\n| PLASMA_METRICS_INTERVAL                         | time.Duration | interval for update metrics                                                           | 10s               |                                                                                    |\n| PLASMA_METRICS_LOG_OUT                          | string        | log file path                                                                         | stdout            |                                                                                    |\n| PLASMA_METRICS_LOG_PREFIX                       | string        | log prefix                                                                            | metrics           |                                                                                    |\n| PLASMA_METRICS_LOG_FLAG                         | int           | define which text to prefix to each log entry generated by the Logger                 | log.Lmicroseconds | https://golang.org/pkg/log/#pkg-constants                                          |\n| PLASMA_METRICS_LOG_INTERVAL                     | time.Duration | interval for send to logger                                                           | 1m                |                                                                                    |\n| PLASMA_METRICS_SYSLOG_TAG                       | string        | tag for syslog                                                                        | plasma            |                                                                                    |\n| PLASMA_METRICS_SYSLOG_INTERVAL                  | time.Duration | interval for send to syslog                                                           | 1m                |                                                                                    |\n| PLASMA_METRICS_SYSLOG_SEVERITY                  | int           | syslog serverity                                                                      | 0                 | https://golang.org/pkg/log/syslog/#Priority                                        |\n| PLASMA_METRICS_SYSLOG_FACILITY                  | int           | syslog facility                                                                       | 0                 | https://golang.org/pkg/log/syslog/#Priority                                        |\n| PLASMA_METRICS_SYSLOG_NETWORDK                  | string        | network for syslog                                                                    |                   |                                                                                    |\n| PLASMA_METRICS_SYSLOG_ADDR                      | string        | address for syslog                                                                    |                   |                                                                                    |\n\n\nLicense\n===\nSee [LICENSE](LICENSE).\n\nCopyright © CyberAgent, Inc. All Rights Reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensaasstudio%2Fplasma","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopensaasstudio%2Fplasma","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopensaasstudio%2Fplasma/lists"}