Commit 067fad7f authored by Corey O'Connor's avatar Corey O'Connor
Browse files

Update README.md, docs/DeepDives.md files

parent b4097530
......@@ -285,6 +285,7 @@ To determine what services fragments we can instantiate query the `/_ops/service
$ curl localhost:10000/_ops/services.json
[
"glngn.server.services.StringValues$",
"glngn.server.services.IntegerCounters$"
]
~~~
......@@ -323,9 +324,7 @@ We already know the logical service ID (`logicalServiceId`) from the query to `/
`serviceId` is an identifier we can pick ourselves. We will pick `retail` for this example.
~~~
$ curl --data '{ "serviceId": "retail", \
"logicalServiceId": "glngn.server.services.IntegerCounters$" \
}' localhost:10000/accounts/_ops/services
$ curl --data '{ "serviceId": "retail", "logicalServiceId": "glngn.server.services.IntegerCounters$" }' localhost:10000/accounts/_ops/services
{
"retail" : [
"glngn.server.services.IntegerCounters$"
......@@ -337,18 +336,126 @@ Which replies with the new set of services under that group. This reply states t
is a composition of a list of service fragments. Which only contains
`glngn.server.services.IntegerCounters$` in this example.
See [docs/Deep Dives](https://gitlab.com/glngn/glngn-server-examples/blob/master/docs/DeepDives.md) for
details.
#### Use a Service
With a service fragment instantiated under a group we can note the OpenAPI schema now includes routes
for the `/accounts/retail` service:
TODO:
##### The Extended OpenAPI Schema
With this fragment instantiated under `/accounts/retail` the service's routes are now visible in the
OpenAPI schema:
~~~
$ curl localhost:10000/openapi.json
{
"openapi" : "3.0.1",
"info" : {
"title" : "dynamic",
"version" : "0.1"
},
"paths" : {
"/accounts/retail/{Entity ID}" : {
"get" : {
...
}
}
},
"/accounts/retail/{Entity ID}/inc" : {
"post" : {
...
}
}
},
"/accounts/retail/{Entity ID}/dec" : {
"post" : {
...
}
}
}
}
}
~~~
- `/accounts/retail/{Entity ID}`
- A query, `GET`, that returns an integer given an `Entity ID`
- `/accounts/retail/{Entity ID}/inc`
- A command, `POST`, that returns the new value of a given `Entity ID` when provided an increment amount.
- `/accounts/retail/{Entity ID}/dec`
- A command, `POST`, that returns the new value of a given `Entity ID` when provided a decrement amount.
1. show dynamic instantiation of a service fragment in OpenAPI schema.
2. demo using the counter service fragment
##### Note: Entity ID
An `Entity ID` is a common path component and identifier in glngn server. All `Entity ID`s are:
- case insensitive
- case preserving
- consist only of characters in `[a-zA-Z0-9\\-_]`: Upper or lower case letters, numbers, '-' and '_'.
- all invalid characters are filtered if provided for an Entity ID
- no longer than 28 characters
Adding new service fragments using the glngn server with the [Developer SDK](docs/Customization.md)
can be used to constrain the domain of identifiers.
##### Get a Counter
~~~
$ curl localhost:10000/accounts/retail/central-store
{
"value" : 0
}
~~~
This is a query for the `retail` counter `central-store`. The result is a value of 0.
Creating the counter prior to querying was not required in this case. Counters default to 0. This
is a useful default and customizable with the [Developer SDK](docs/Customization.md).
##### Increment a Counter
Using the `inc` subroute the counter can be incremented by a given value:
~~~
$ curl --data 10 localhost:10000/accounts/retail/central-store/inc
{
"value" : 10
}
$ curl --data 12 localhost:10000/accounts/retail/central-store/inc
{
"value" : 22
}
$ curl localhost:10000/accounts/retail/central-store
{
"value" : 22
}
~~~
##### Events Persists
If the glngn server application was to be restarted then this data would persist. If the counter
was queried after restart the value would be the same as before.
The server is persisting all events that modified that counter. Each of those `inc` and `dec`
used to change a counter is saved. This history is essential to "event sourcing". Having a
history, not only the current state, of a service enables a new level of analysis of your
business activity.
The standalone version persists to the directory provided to the `--state` command line argument.
When deployed to kubernetes the service can also persist to a database such as Amazon's DynamoDB
or Cassandra.
#### Capturing Events
If we have a model of our business events we can build and instantiate service fragments that
reflect that model. What do we do if we don't have a model of our business events? These unknowns are likely
in a number of situations: New business proposals; exceptional business events; unexpected issues. These
will not have a schema or service structure a-priori. This is why glngn server supports arbitrary
events to enable your business to start building a model.
TODO:
1. demo capturing unmodeled events:
......
......@@ -49,3 +49,22 @@ that is difficult to provide with a modular build. The
assembly is built and verified against specific versions of dependent libraries.
The non-modular build permits adding or changing dependents. However, this
invalidates the prior assurances to a degree.
## Service Fragment Instantiation
### Service Fragments with the same service ID
Multiple service fragments may be instantiated under a service ID. This is subject to the
conditions:
1. Each service fragment must have a unique logical ID.
2. The service fragment endpoints must be disjoint
3. The service fragment event schema must be disjoint
### Can any class be instantiated?
No. While the routes accept class names these must be in the whitelisted set of
classes provided in the `Prelude`.
This set can only be changed by building a customized version of glngn server and using
that build.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment