add english docs detail

docs/README.md

@@ -15,7 +15,7 @@
 ### <font color="green">`Introduction`</font>
 
 > `sureness` 是作者在使用`java`权限框架`shiro`之后,吸取其良好的设计加上一些自己想法实现的全新认证鉴权项目  
->  面对`restful api`的认证鉴权,基于`RABC`主要关注于对`restful api`的保护  
+>  面对`restful api`的认证鉴权,基于`RBAC`主要关注于对`restful api`的保护  
 >  原生支持 `restful api, websocket protection`  
 >  原生支持动态权限(权限配置的动态加载)  
 >  原生支持 `jwt`, `Basic Auth` ... 可扩展自定义支持的认证方式  

docs/_coverpage.md

@@ -4,7 +4,7 @@
 
 > A simple and efficient open-source security framework that focus on protection for restful api.
 
-- 面对`restful api`的认证鉴权,基于`RABC`主要关注于对`restful api`的保护
+- 面对`restful api`的认证鉴权,基于`RBAC`主要关注于对`restful api`的保护
 - 原生支持 `restful api, websocket protection`
 - 原生支持动态权限(权限配置的动态加载)  
 - 原生支持 `jwt`, `Basic Auth` ... 可扩展自定义支持的认证方式  

docs/_sidebar.md

@@ -15,4 +15,4 @@
 - 其它
   - [设计文档](design.md)
   - [参与贡献](contributing.md)
-  - [changelog](https://github.com/tomsun28/sureness/commits/master ':ignore')
+  - [changelog](https://github.com/tomsun28/sureness/releases ':ignore')

docs/en/README.md

@@ -2,7 +2,6 @@
 
 [![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)  
 
-[中文文档](README.md)  
 
 ## <font color="green">`Introduction`</font>
 
@@ -12,123 +11,5 @@
 > Native supports  restful api, websocket's protection  
 > Native supports dynamic permissions  
 > Native supports JWT, Basic Auth... Can extend custom supported authentication methods  
-> [High performance due dictionary matching tree](#Why Is High Performance)  
-> Sorry about google english.   
-
-### Components of Repository:  
-- [sureness's kernel code--sureness-core](core)  
-- [10 Minute Tutorial's Program--sample-bootstrap](sample-bootstrap)  
-- [30 Minute Tutorial's Program--sample-tom](sample-tom)  
-
-### <font color="red">Some Conventions</font>  
-
-- Based RBAC, but only has role-resource, no permission action    
-- We treat restful requests as a resource, resource format like `requestUri===httpMethod`.   
-  That is the request uri + request method(`post,get,put,delete...`) is considered as a resource as a whole.  
-  `eg: /api/v2/book===get`    
-- User belong some Role -- Role owns Resource -- User can access the resource  
-
-### Use  
-
-`maven`  
-```
-<!-- https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core -->
-<dependency>
-    <groupId>com.usthe.sureness</groupId>
-    <artifactId>sureness-core</artifactId>
-    <version>0.0.2.6</version>
-</dependency>
-```
-
-`gradle`  
-```
-compile group: 'com.usthe.sureness', name: 'sureness-core', version: '0.0.2.6'
-```
-
-Portal, always is a filter intercepting all requests:  
-```
-SurenessSecurityManager.getInstance().checkIn(servletRequest)
-```
-
-Authentication passed directly, failure throw exception, catch exception and do something:   
-
-```
-        try {
-            SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
-        } catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
-            // Create subject error related execption 
-        } catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
-            // Account disable related exception
-        } catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
-            // Authentication failure related exception
-        } catch (UnauthorizedException e5) {
-            // Authorization failure related exception
-        } catch (RuntimeException e) {
-            // other sureness exception
-        }
-```
-
-sureness exception                              | exception note
----                                                             | ---
-SurenessAuthenticationException     |  basic authenticated exception,Authentication related extend it
-SurenessAuthorizationException       | basic authorized exception,Authorization related extend it
-ProcessorNotFoundException            | authenticated,not found process support this subject
-UnknownAccountException                | authenticated,unknown account
-UnSupportedSubjectException           | authenticated,unSupport request
-DisabledAccountException                  | authenticated,account disable
-ExcessiveAttemptsException                | authenticated,excessive attempts
-IncorrectCredentialsException             | authenticated, incorrect credential
-ExpiredCredentialsException               | authenticated,expired credential
-UnauthorizedException                        | authorized,no permission access this resource
-
-custom exception should extend SurenessAuthenticationException or SurenessAuthorizationException  
-
-If the configuration resource data comes from text, please refer to  [10 Minute Tutorial's Program--sample-bootstrap](sample-bootstrap)   
-If the configuration resource data comes from database, please refer to  [30 Minute Tutorial's Program--sample-tom](sample-tom)   
-
-Have Fun   
-
-
-### Advanced Use  
-
-if know sureness [Process flow](#Process flow), maybe know the extend point  
-
-sureness support custom subject, custom subjectCreator, custom processor and more.  
-
-suggest look these interface before extending:  
-
-- `Subject`:  Authenticated authorized  user's account interface, provide the account's username,password, request resources, roles, etc.  
-- `SubjectCreate`: create subject interface, provider create method   
-- `Processor`:  process subject interface, where happen authentication and authorization 
-- `PathTreeProvider`: resource data provider, it can load data from txt or database,etc
-- `SurenessAccountProvider`: account data provider, it can load data from txt or database,etc   
-
-
-1. **custom datasource**  
-
-`implment PathTreeProvider, load in DefaultPathRoleMatcher`   
-`implment SurenessAccountProvide, load in processor`  
-
-2. **custom subject**  
-
-`implment Subject, add custom subject content`  
-`implment SubjectCreate to create custom subject`  
-`implment Processor to support custom subject`    
-
-3. **custom processor**  
-
-`a subject also can support by different processor, so we can custom processor to support custom subject`
-`implment Processor, set which subject can support and implment processing details`  
-
-Detail please refer to  [30 Minute Tutorial's Program--sample-tom](sample-tom)   
-
-### Why Is High Performance  
-
-![pathRoleMatcher](../_images/PathRoleMatcher.svg)  
-
-### Process flow  
-
-![sureness-core](../_images/sureness-core.svg)  
-
-### License  
-[`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)
\ No newline at end of file
+> High performance due dictionary matching tree
+> Sorry about google english.   
\ No newline at end of file

docs/en/_sidebar.md

 - Start  
-  - [Introduce](en/sureness.md "The greatest")  
\ No newline at end of file
+  - [Introduce](README.md "introduce")
+  - [Quick Start](quickstart.md "quick start greatest")  
+
+- Advanced Extend
+  - [extend point](extend-point.md)
+  - [custom datasource](custom-datasource.md)
+  - [custom subject](custom-subject.md)
+  - [custom processor](custom-processor.md)
+
+- Integration Demo
+  - [10 Minute Tutorial](sample-bootstrap.md)
+  - [30 Minute Tutorial](sample-tom.md)
+
+- Others
+  - [Design](design.md)
+  - [Contribute to us](contributing.md)
+  - [changelog](https://github.com/tomsun28/sureness/releases ':ignore')

docs/en/contributing.md

+Contributing to sureness
+=======================================
+
+Summary
+-------
+This document covers how to contribute to the sureness project. These instructions assume you have a GitHub.com account, so if you don't have one you will have to create one. Your proposed code changes will be published to your own fork of the sureness project and you will submit a Pull Request for your changes to be added.
+
+_Lets get started!!!_
+
+
+Fork the code
+-------------
+
+In your browser, navigate to: [https://github.com/tomsun28/sureness](https://github.com/tomsun28/sureness)
+
+Fork the repository by clicking on the 'Fork' button on the top right hand side.  The fork will happen and you will be taken to your own fork of the repository.  Copy the Git repository URL by clicking on the clipboard next to the URL on the right hand side of the page under '**HTTPS** clone URL'.  You will paste this URL when doing the following `git clone` command.
+
+On your computer, follow these steps to setup a local repository for working on sureness:
+
+``` bash
+$ git clone https://github.com/YOUR_ACCOUNT/sureness.git
+$ cd sureness
+$ git remote add upstream https://github.com/tomsun28/sureness.git
+$ git checkout master
+$ git fetch upstream
+$ git rebase upstream/master
+```
+
+
+Making changes
+--------------
+
+It is important that you create a new branch to make changes on and that you do not change the `master` branch (other than to rebase in changes from `upstream/master`).  In this example I will assume you will be making your changes to a branch called `feature_x`.  This `feature_x` branch will be created on your local repository and will be pushed to your forked repository on GitHub.  Once this branch is on your fork you will create a Pull Request for the changes to be added to the sureness project.
+
+It is best practice to create a new branch each time you want to contribute to the project and only track the changes for that pull request in this branch.
+
+``` bash
+$ git checkout -b feature_x
+   (make your changes)
+$ git status
+$ git add .
+$ git commit -a -m "descriptive commit message for your changes"
+```
+
+> The `-b` specifies that you want to create a new branch called `feature_x`.  You only specify `-b` the first time you checkout because you are creating a new branch.  Once the `feature_x` branch exists, you can later switch to it with only `git checkout feature_x`.
+
+
+Rebase `feature_x` to include updates from `upstream/master`
+------------------------------------------------------------
+
+It is important that you maintain an up-to-date `master` branch in your local repository.  This is done by rebasing in the code changes from `upstream/master` into your local repository.  You will want to do this before you start working on a feature as well as right before you submit your changes as a pull request.  I recommend you do this process periodically while you work to make sure you are working off the most recent project code.
+
+This process will do the following:
+
+1. Checkout your local `master` branch
+2. Synchronize your local `master` branch with the `upstream/master` so you have all the latest changes from the project
+3. Rebase the latest project code into your `feature_x` branch so it is up-to-date with the upstream code
+
+``` bash
+$ git checkout master
+$ git fetch upstream
+$ git rebase upstream/master
+$ git checkout feature_x
+$ git rebase master
+```
+
+> Now your `feature_x` branch is up-to-date with all the code in `upstream/master`.
+
+
+Make a GitHub Pull Request to contribute your changes
+-----------------------------------------------------
+
+When you are happy with your changes and you are ready to contribute them, you will create a Pull Request on GitHub to do so.  This is done by pushing your local changes to your forked repository (default remote name is `origin`) and then initiating a pull request on GitHub.
+
+> **IMPORTANT:** Make sure you have rebased your `feature_x` branch to include the latest code from `upstream/master` _before_ you do this.
+
+``` bash
+$ git push origin master
+$ git push origin feature_x
+```
+
+Now that the `feature_x` branch has been pushed to your GitHub repository, you can initiate the pull request.
+
+To initiate the pull request, do the following:
+
+1. In your browser, navigate to your forked repository: [https://github.com/YOUR_ACCOUNT/sureness](https://github.com/tomsun28/sureness)
+2. Click the new button called '**Compare & pull request**' that showed up just above the main area in your forked repository
+3. Validate the pull request will be into the upstream `master` and will be from your `feature_x` branch
+4. Enter a detailed description of the work you have done and then click '**Send pull request**'
+
+If you are requested to make modifications to your proposed changes, make the changes locally on your `feature_x` branch, re-push the `feature_x` branch to your fork.  The existing pull request should automatically pick up the change and update accordingly.
+
+
+Cleaning up after a successful pull request
+-------------------------------------------
+
+Once the `feature_x` branch has been committed into the `upstream/master` branch, your local `feature_x` branch and the `origin/feature_x` branch are no longer needed.  If you want to make additional changes, restart the process with a new branch.
+
+> **IMPORTANT:** Make sure that your changes are in `upstream/master` before you delete your `feature_x` and `origin/feature_x` branches!
+
+You can delete these deprecated branches with the following:
+
+``` bash
+$ git checkout master
+$ git branch -D feature_x
+$ git push origin :feature_x
+```

docs/en/custom-datasource.md

+## custom datasource  
+
+`implment PathTreeProvider, load in DefaultPathRoleMatcher`   
+`implment SurenessAccountProvide, load in processor`  
+
+Detail please refer to  [30 Minute Tutorial's Program--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)   

docs/en/custom-processor.md

+## custom processor  
+
+`a subject also can support by different processor, so we can custom processor to support custom subject`
+`implment Processor, set which subject can support and implment processing details`  
+
+Detail please refer to  [30 Minute Tutorial's Program--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)   

docs/en/custom-subject.md

+## custom subject
+
+`implment Subject, add custom subject content`  
+`implment SubjectCreate to create custom subject`  
+`implment Processor to support custom subject`    
+
+Detail please refer to  [30 Minute Tutorial's Program--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)   

docs/en/design.md

+### Why Is High Performance  
+
+![pathRoleMatcher](../_images/PathRoleMatcher.svg)  
+
+### Process flow  
+
+![sureness-core](../_images/sureness-core.svg)  

docs/en/extend-point.md

+## Advanced Use  
+
+if know sureness Process flow, maybe know the extends point  
+
+sureness supports custom subject, custom subjectCreator, custom processor and more.  
+
+suggest look these interface before extending:  
+
+- `Subject`: Authenticated authorized  user's account interface, provide the account's username,password, request resources, roles, etc.  
+- `SubjectCreate`: create subject interface, provider create method.    
+- `Processor`:  process subject interface, where happen authentication and authorization.   
+- `PathTreeProvider`: resource data provider, it can load data from txt or database,etc.  
+- `SurenessAccountProvider`: account data provider, it can load data from txt or database,etc.     

docs/en/sureness.md → docs/en/quickstart.md

-# `sureness`  
-
-[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)  
-
-[中文文档](README.md)  
-
-## <font color="green">`Introduction`</font>
-
-
-> Sureness is a new, permission project which author learn from apache shiro and add some ideas to create it  
-> Authentication for restful api, based on RBAC, Mainly focused on the protection of restful api  
-> Native supports  restful api, websocket's protection  
-> Native supports dynamic permissions  
-> Native supports JWT, Basic Auth... Can extend custom supported authentication methods  
-> [High performance due dictionary matching tree](#Why Is High Performance)  
-> Sorry about google english.   
-
-### Components of Repository:  
-- [sureness's kernel code--sureness-core](core)  
-- [10 Minute Tutorial's Program--sample-bootstrap](sample-bootstrap)  
-- [30 Minute Tutorial's Program--sample-tom](sample-tom)  
-
-### <font color="red">Some Conventions</font>  
+## <font color="red">Some Conventions</font>  
 
 - Based RBAC, but only has role-resource, no permission action    
 - We treat restful requests as a resource, resource format like `requestUri===httpMethod`.   
   That is the request uri + request method(`post,get,put,delete...`) is considered as a resource as a whole.  
   `eg: /api/v2/book===get`    
-- User belong some Role -- Role owns Resource -- User can access the resource  
+- User belongs some Role -- Role owns Resource -- User can access the resource  
+
+## Quick Use  
 
-### Use  
+### add sureness in project  
 
-`maven`  
+1. when use maven build project, add maven coordinate  
 ```
 <!-- https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core -->
 <dependency>
@@ -39,17 +19,26 @@
     <version>0.0.2.6</version>
 </dependency>
 ```
-
-`gradle`  
+2. when use gradle build project, add gradle coordinate  
 ```
 compile group: 'com.usthe.sureness', name: 'sureness-core', version: '0.0.2.6'
 ```
+3. when not java build project, add sureness-core.jar to classPath  
+```
+download this jar at mvnrepository  
+https://mvnrepository.com/artifact/com.usthe.sureness/sureness-core
+```
+
+### add an interceptor intercepting all requests  
 
-Portal, always is a filter intercepting all requests:  
+the interceptor can be a filter or a spring interceptor.  
+the interceptor intercepts all request to check them.  
 ```
 SurenessSecurityManager.getInstance().checkIn(servletRequest)
 ```
 
+
+### implement exception flow when exception throw  
 Authentication passed directly, failure throw exception, catch exception and do something:   
 
 ```
@@ -83,52 +72,61 @@ UnauthorizedException                        | authorized,no permission access t
 
 custom exception should extend SurenessAuthenticationException or SurenessAuthorizationException  
 
-If the configuration resource data comes from text, please refer to  [10 Minute Tutorial's Program--sample-bootstrap](sample-bootstrap)   
-If the configuration resource data comes from database, please refer to  [30 Minute Tutorial's Program--sample-tom](sample-tom)   
-
-Have Fun   
-
-
-### Advanced Use  
+### load config dataSource   
 
-if know sureness [Process flow](#Process flow), maybe know the extend point  
-
-sureness support custom subject, custom subjectCreator, custom processor and more.  
-
-suggest look these interface before extending:  
-
-- `Subject`:  Authenticated authorized  user's account interface, provide the account's username,password, request resources, roles, etc.  
-- `SubjectCreate`: create subject interface, provider create method   
-- `Processor`:  process subject interface, where happen authentication and authorization 
-- `PathTreeProvider`: resource data provider, it can load data from txt or database,etc
-- `SurenessAccountProvider`: account data provider, it can load data from txt or database,etc   
-
-
-1. **custom datasource**  
-
-`implment PathTreeProvider, load in DefaultPathRoleMatcher`   
-`implment SurenessAccountProvide, load in processor`  
-
-2. **custom subject**  
-
-`implment Subject, add custom subject content`  
-`implment SubjectCreate to create custom subject`  
-`implment Processor to support custom subject`    
-
-3. **custom processor**  
-
-`a subject also can support by different processor, so we can custom processor to support custom subject`
-`implment Processor, set which subject can support and implment processing details`  
-
-Detail please refer to  [30 Minute Tutorial's Program--sample-tom](sample-tom)   
-
-### Why Is High Performance  
-
-![pathRoleMatcher](../_images/PathRoleMatcher.svg)  
+sureness need dataSource to authenticate and authorize, eg: role data, user data etc.  
+the dataSource can load from txt, dataBase or no dataBase etc.
+we provide interfaces `SurenessAccountProvider`, `PathTreeProvider` for user implement to load data from the dataSource where they want.
+also, we provide default dataSource implement which load dataSource from txt(sureness.yml), user can defined their data in sureness.yml. 
+eg:  
+```
+## -- sureness.yml txt dataSource-- ##
+
+# load api resource which need be protected.
+# eg: /api/v2/host===post===[role2,role3,role4] means /api/v2/host===post is be role2,role3,role4 supported access
+# eg: /api/v1/getSource3===get===[] means /api/v1/getSource3===get is be all role or no role supported access
+resourceRole:
+  - /api/v2/host===post===[role2,role3,role4]
+  - /api/v2/host===get===[role2,role3,role4]
+  - /api/v2/host===delete===[role2,role3,role4]
+  - /api/v2/host===put===[role2,role3,role4]
+  - /api/mi/**===put===[role2,role3,role4]
+  - /api/v1/getSource1===get===[role1,role2]
+  - /api/v2/getSource2/*/*===get===[role2]
+  - /api/v1/source1===get===[role2]
+  - /api/v1/source1===post===[role1]
+  - /api/v1/source1===delete===[role3]
+  - /api/v1/source1===put===[role1,role2]
+  - /api/v1/source2===get===[]
+
+# load api resource wich do not need be proetcted, means them need be filtering.
+# these api resource can be access by everyone
+excludedResource:
+  - /api/v3/host===get
+  - /api/v3/book===get
+  - /api/v1/account/auth===post
+
+# account info
+# there are three account: admin root tom
+# eg: admin has [role1,role2] ROLE, encrypted password is 0192023A7BBD73250516F069DF18B500
+# eg: root has no ROLE, no encrypted password is 23456
+account:
+  - appId: admin
+    # if add salt, the password is encrypted password - the result MD5(password+salt)
+    # if no salt, the password is no encrypted password
+    credential: 0192023A7BBD73250516F069DF18B500
+    salt: 123
+    role: [role1,role2]
+  - appId: root
+    credential: 23456
+    role: [role1]
+  - appId: tom
+    credential: 32113
+    role: [role2]
 
-### Process flow  
+```
 
-![sureness-core](../_images/sureness-core.svg)  
+If the configuration resource data comes from text, please refer to  [10 Minute Tutorial's Program--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)   
+If the configuration resource data comes from dataBase, please refer to  [30 Minute Tutorial's Program--sample-tom](https://github.com/tomsun28/sureness/tree/master/sample-tom)   
 
-### License  
-[`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)
\ No newline at end of file
+**Have Fun**     
\ No newline at end of file

docs/en/sample-bootstrap.md

+## sample-bootstrap  
+
+[sureness 10 Minute Tutorial](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)  
+
+- based on `springboot`
+- load data from default dataSource - `sureness.yml`
+- use default sureness config
+- use default `jwt,basic auth` to authenticate and authorize
+- contain `restful api,websocket`  
+- project's protected entrance is `SurenessFilterExample`
+- suggest use postman to test, test case is in `sample-bootstrap-postman.json`, user can load it in postman  

docs/en/sample-tom.md

+## sample-tom  
+
+[sureness 30 Minute Tutorial](https://github.com/tomsun28/sureness/tree/master/sample-tom)  
+
+- based on `springboot`
+- load data from mysql dataBase dataSource, then user can modify their data dynamically
+- apart from having default `jwt,basic auth`, it adds custom `subject subjectCreator processor` to define new auth type.
+- project's protected entrance is `SurenessFilterExample`
+- suggest use postman to test, test case is in `sample-tom-postman.json`, user can load it in postman  

docs/extend-point.md

-### 进阶扩展  
+## 进阶扩展  
 
-如果了解 [处理流程](#处理流程),就大概知道`sureness`提供的扩展点    
+如果了解处理流程,就大概知道`sureness`提供的扩展点    
 `sureness`支持自定义`subject`，自定义`subjectCreator`注册，自定义`processor`处理器等  
 
 扩展之前需要了解以下接口:  

docs/quickstart.md

 ## <font color="red">使用前一些约定</font>  
 
-- `sureness`尽量简洁,基于`RABC`,但只有(角色-资源)的映射,没有(权限)动作映射
+- `sureness`尽量简洁,基于`RBAC`,但只有(角色-资源)的映射,没有(权限)动作映射
 - 我们将`restful api`请求视作一个资源,资源格式为: `requestUri===httpMethod`  
   即请求的路径加上其请求方式(`post,get,put,delete...`)作为一个整体被视作一个资源  
   `eg: /api/v2/book===get` `get`方式请求`/api/v2/book`接口数据