Skip to content

Commit

Permalink
Merge pull request #5 from Mercap/package_splitting
Browse files Browse the repository at this point in the history
Package splitting
  • Loading branch information
juliendelplanque authored Jun 14, 2019
2 parents 5f6f41e + 4ce34f8 commit 7831ad2
Show file tree
Hide file tree
Showing 45 changed files with 271 additions and 177 deletions.
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
*.st linguist-language=Smalltalk
22 changes: 11 additions & 11 deletions .smalltalk.ston
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
SmalltalkCISpec {
#loading : [
SCIMetacelloLoadSpec {
#baseline : 'JRPC',
#directory : 'src',
#platforms : [ #pharo ]
}
],
#testing : {
#categories : [ 'JRPC-Tests' ],
#coverage : {
#categories : [ 'JRPC-Tests' ]
#loading : [
SCIMetacelloLoadSpec {
#baseline : 'JRPC',
#directory : 'src',
#load : [ 'CI' ],
#platforms : [ #pharo ]
}
],
#testing : {
#coverage : {
#packages : [ 'JRPC-Client' , 'JRPC-Server' , 'JRPC-Tests' ]
}
}
}
19 changes: 10 additions & 9 deletions .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,17 @@ language: smalltalk
sudo: false

notifications:
email:
on_success: never
on_failure: always
email:
on_success: never
on_failure: always

os:
- linux
- osx
- linux
- osx

smalltalk:
- Pharo-6.1
- Pharo-7.0
- Pharo32-8.0
- Pharo64-8.0
- Pharo32-6.1
- Pharo64-7.0
- Pharo32-7.0
- Pharo32-8.0
- Pharo64-8.0
31 changes: 31 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
Contributing
============

There's several ways to contribute to the project: reporting bugs, sending feedback, proposing ideas for new features, fixing or adding documentation, promoting the project, or even contributing code.

## Reporting issues

You can report issues [here](https://github.com/juliendelplanque/JRPC/issues/new)

## Contributing Code
- This project is MIT licensed, so any code contribution MUST be under the same license.
- This project uses [Semantic Versioning](http://semver.org/), so keep it in mind when you make backwards-incompatible changes. If some backwards incompatible change is made the major version MUST be increased.
- The source code is hosted in this repository using the Tonel format in the `src` folder.
- The `master` branch contains the latest changes.
- Feel free to send pull requests or fork the project.

### Using Iceberg
1. Download a [Pharo Image and VM](https://get.pharo.org/64)
2. Clone the project or your fork using Iceberg
3. Open the Working Copy and using the contextual menu select `Metacello -> Install baseline...`
4. Input `Development`
5. This will load the base code and the test cases
6. Create a new branch to host your code changes
7. Do the changes
8. Run the test cases
9. Commit and push your changes to the branch using the Iceberg UI
10. Create a Pull Request against the `master` branch

## Contributing documentation

The project documentation is maintained in this repository in the `docs` folder. To contribute some documentation or improve the existing, feel free to create a branch or fork this repository, make your changes and send a pull request.
2 changes: 1 addition & 1 deletion LICENSE
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
MIT License

Copyright (c) 2018 Julien Delplanque
Copyright (c) 2018-2019 Julien Delplanque

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
Expand Down
128 changes: 13 additions & 115 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
# JRPC
# JRPC
[![Build Status](https://travis-ci.org/juliendelplanque/JRPC.svg?branch=master)](https://travis-ci.org/juliendelplanque/JRPC)
[![Coverage Status](https://coveralls.io/repos/github/juliendelplanque/JRPC/badge.svg?branch=master)](https://coveralls.io/github/juliendelplanque/JRPC?branch=master)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Pharo version](https://img.shields.io/badge/Pharo-6.1-%23aac9ff.svg)](https://pharo.org/download)
[![Pharo version](https://img.shields.io/badge/Pharo-7.0-%23aac9ff.svg)](https://pharo.org/download)
Expand All @@ -8,13 +9,10 @@
Yet another [JSON-RPC 2.0](https://www.jsonrpc.org/specification) implementation for Pharo Smalltalk

- [Features](#features)
- [Installation](#installation)
- [Examples](#examples)
* [Client](#client)
* [Server](#server)
- [Additional data provided in error messages](#additional-data-provided-in-error-messages)
- [Version management](#version-management)
- [Install](#install)
- [JRPC v.s. others](#jrpc-vs-others)
- [Comparison with other JSON RPC implementations](#jrpc-vs-others)
- [Contributing](#contributing)

## Features
- Client and Server support for JSON-RPC 2.0.
Expand All @@ -25,122 +23,22 @@ Yet another [JSON-RPC 2.0](https://www.jsonrpc.org/specification) implementation
- Additional `data` when an error occured in the `error` object.

## Examples
### Client
Given a server using HTTP protocol, listening on port 4000 and exposing `'sqrt'` method which computes the square-root of its single parameter, one can write the following:

```Smalltalk
(JRPCClient http: 'http://localhost:4000')
callMethod: 'sqrt' arguments: #(4) withId: 1
```
Explore the [documentation](docs/Examples.md)

The object returned by this expression is an instance of `JRPCSuccessResponseObject`.
Its `result` instance variable contains the result of `sqrt` method applied on `4`. That is to say, it contains `2.0`.
Its `id` instance variable contains the `id` specified previously.
## Installation

Ids allow to map responses returned by the server to requests sent by the client.
Ids are managed by the developer using the client.
To load the project in a Pharo image or declare it as a dependency of your project follow this [instructions](docs/Installation.md).

### Server
To create a server using HTTP protocol, listening on port 4000 and defining an handler for `'sqrt'` which computes the square-root of its single paramter, one can write the following:

```Smalltalk
server := JRPCServer http
port: 4000;
addHandlerNamed: 'sqrt' block: [ :x | x sqrt ];
yourself.
```

To start it, use `#start` method:

```Smalltalk
server start
```

To stop it, use `#stop` method:

```Smalltalk
server stop
```

## Additional data provided in error messages
[JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification) specifies that in error messages, a `data` field can optionally be set to provide additional information about the error. However, this field structure is specified by the server. This section describes what the current implementation stores in the `data` field.

To do that, let's take the following configuration. We have a server defined as follow:
```Smalltalk
server := JRPCServer http
port: 4000;
addHandlerNamed: 'divide' block: [ :x :y | x / y ];
yourself.
server start.
```

This server has a handler implenting a the division of `x` by `y`. In Pharo, dividing a `Number` by `0` results in a `ZeroDivide` error. Thus, the following code:

```Smalltalk
(JRPCClient http: 'http://localhost:4000')
callMethod: 'divide' arguments: #(1 0) withId: 1.
```

Will results in a JSON-RPC error for which the error looks like this in JSON format:

```Smalltalk
{
"jsonrpc" : "2.0",
"id" : 1,
"error" : {
"data" : {
"tag" : "",
"errorClass" : "ZeroDivide",
"signalerContext" : "SmallInteger>>/",
"messageText" : "",
"signaler" : "1"
},
"message" : "Internal JSON-RPC error.",
"code" : -32603
}
}
```

Mind the `data` sub-field inside `error` error field. It contains additional data about the error for which the structure is defined by this particular implementation.

The structure is the following:
```
{
"errorClass" : String, // The class of the Pharo error.
"signaler" : String, // The object to which the message was sent when the error occured.
"signalerContext" : String, // The method in which error was raised formatted as Class>>method
"messageText" : String, // The message the Pharo error hold.
"tag" : String // The tag of the Pharo error.
}
```

## Version management

This project use semantic versionning to define the releases. This mean that each stable release of the project will get associate a version number of the form `vX.Y.Z`.

- **X** define the major version number
- **Y** define the minor version number
- **Z** define the patch version number

When a release contains only bug fixes, the patch number increase. When the release contains new features backward compatibles, the minor version increase. When the release contains breaking changes, the major version increase.

Thus, it should be safe to depend on a fixed major version and moving minor version of this project.

## Install
To install this project, run the following code snippet:
```Smalltalk
Metacello new
repository: 'github://JulienDelplanque/JRPC/src';
baseline: 'JRPC';
load
```

## JRPC v.s. others
## Comparison with other JSON RPC implementations

| Property | JSONRPC | LtJsonRpc | NeoJSONRPC |
|--------------|--------------------|--------------------|--------------------|
| Server | :white_check_mark: | :white_check_mark: | :x: |
| Client | :white_check_mark: | :white_check_mark: | :white_check_mark: |
| JSON backend | STONJSON | Json | NeoJSON |
| Tests | :white_check_mark: | :x: | :x: |

## Contributing

Check the [Contribution Guidelines](CONTRIBUTING.md)
90 changes: 90 additions & 0 deletions docs/Examples.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# Examples
## Client
Given a server using HTTP protocol, listening on port 4000 and exposing `'sqrt'` method which computes the square-root of its single parameter, one can write the following:

```Smalltalk
(JRPCClient http: 'http://localhost:4000')
callMethod: 'sqrt' arguments: #(4) withId: 1
```

The object returned by this expression is an instance of `JRPCSuccessResponseObject`.
Its `result` instance variable contains the result of `sqrt` method applied on `4`. That is to say, it contains `2.0`.
Its `id` instance variable contains the `id` specified previously.

Ids allow to map responses returned by the server to requests sent by the client.
Ids are managed by the developer using the client.

## Server
To create a server using HTTP protocol, listening on port 4000 and defining an handler for `'sqrt'` which computes the square-root of its single paramter, one can write the following:

```Smalltalk
server := JRPCServer http
port: 4000;
addHandlerNamed: 'sqrt' block: [ :x | x sqrt ];
yourself.
```

To start it, use `#start` method:

```Smalltalk
server start
```

To stop it, use `#stop` method:

```Smalltalk
server stop
```

## Additional data provided in error messages
[JSON-RPC 2.0 specification](https://www.jsonrpc.org/specification) specifies that in error messages, a `data` field can optionally be set to provide additional information about the error. However, this field structure is specified by the server. This section describes what the current implementation stores in the `data` field.

To do that, let's take the following configuration. We have a server defined as follow:
```Smalltalk
server := JRPCServer http
port: 4000;
addHandlerNamed: 'divide' block: [ :x :y | x / y ];
yourself.
server start.
```

This server has a handler implenting a the division of `x` by `y`. In Pharo, dividing a `Number` by `0` results in a `ZeroDivide` error. Thus, the following code:

```Smalltalk
(JRPCClient http: 'http://localhost:4000')
callMethod: 'divide' arguments: #(1 0) withId: 1.
```

Will results in a JSON-RPC error for which the error looks like this in JSON format:

```Smalltalk
{
"jsonrpc" : "2.0",
"id" : 1,
"error" : {
"data" : {
"tag" : "",
"errorClass" : "ZeroDivide",
"signalerContext" : "SmallInteger>>/",
"messageText" : "",
"signaler" : "1"
},
"message" : "Internal JSON-RPC error.",
"code" : -32603
}
}
```

Mind the `data` sub-field inside `error` error field. It contains additional data about the error for which the structure is defined by this particular implementation.

The structure is the following:
```
{
"errorClass" : String, // The class of the Pharo error.
"signaler" : String, // The object to which the message was sent when the error occured.
"signalerContext" : String, // The method in which error was raised formatted as Class>>method
"messageText" : String, // The message the Pharo error hold.
"tag" : String // The tag of the Pharo error.
}
```
46 changes: 46 additions & 0 deletions docs/Installation.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Installation

## Basic Installation

You can load **JRPC** evaluating:
```smalltalk
Metacello new
baseline: 'JRPC';
repository: 'github://juliendelplanque/JRPC:master/src';
load.
```
> Change `master` to some released version if you want a pinned version
## Using as dependency

In order to include **JRPC** as part of your project, you should reference the package in your product baseline:

```smalltalk
setUpDependencies: spec
spec
baseline: 'JRPC'
with: [ spec
repository: 'github://juliendelplanque/JRPC:v{XX}/src';
loads: #('Deployment') ];
import: 'JRPC'.
```
> Replace `{XX}` with the version you want to depend on
```smalltalk
baseline: spec
<baseline>
spec
for: #common
do: [ self setUpDependencies: spec.
spec package: 'My-Package' with: [ spec requires: #('JRPC') ] ]
```

## Provided groups
- `Server-Deployment` will load all the packages needed to deploy a JSON RPC Server
- `Client-Deployemnt` will load all the packages needed to deploy a JSON RPC Client
- `Deployment` will load all the packages needed to deploy both a JSON RPC Client and Server
- `Tests` will load the test cases
- `CI` is the group loaded in the continuous integration setup
- `Development` will load all the needed packages to develop and contribute to the project
Loading

0 comments on commit 7831ad2

Please sign in to comment.