I recall the days when I started writing my first line of code on my Pentium 75 PC. It was the late 90s and the economic forecast in my home country was bleak. High inflation rates relentlessly squeezed the mid-class to the brink. Six days workweek was almost the norm in Turkey. My dad worked tirelessly, but a PC was actually a luxury item. Savings were dwindled long before we could afford to buy a PC.

So it took a decade before we could afford a PC. In the meantime, I grew up and started high school in my hometown. I already had a few programming hours under my belt at the high school, which was unusual for a state school at that time to offer students a computer lab and teach programming. Basic was the very first programming language that I learned. The progress of learning sped up as I got my first personal computer. Pascal, Delphi, C, C++, and many more. I was trying to write a software to chat with other people over a barely connected computer via a 56K modem. Or to understand how to develop my own VCL components in Delphi. Even I tried to write my own operating system with C but quickly lost my focus once I discovered the speed of feedback loop with web development.

I wrote countless lines of code across many programming languages. One habit became second nature: backing up my code. Initially, I relied on copies on a separate hard-disk partition, but later, after I purchased a second-hand 4x CD-writer, started burning them onto CDs. I still have the copies from the 90s today and review my code thirty years later. I eventually created a personal code inventory, which I can pull out when I need to revive my coding skills in a specific programming language. Today, the compact disks maybe do not exist anymore, but there are better options than burning data onto a hard medium. The service providers like Gitlab, Github, Bitbucket, etc. offer free version-controlling options, which you can use to create your inventory within seconds.

But, what is the value of creating a personal code inventory and maintaining it? A code inventory is like a collection of old photographs—it lets you compare your current coding skills to your past ones. I occasionally dig up old projects and review them just for fun. Sometimes, the old code disappoints me, and it can even be a little embarrassing when I realize I published my spaghetti code online without any tests. But that’s okay. More often than not, though, I’m amazed by the solutions I came up with in my mid-20s or the elegant designs I crafted from scratch.

An inventory can also help you kickstart new projects by repurposing reusable components from past ideas. That’s why it’s important to aim for higher standards, even when working on hobby projects or prototyping ideas. Keep in mind—the code you write today might still be valuable years down the line.

Maintaining a public project inventory also gives you the opportunity to collaborate with other developers. By publishing your projects on public Git repositories, you can contribute to the open-source community. When sharing your code, it’s important to maintain high-quality standards because the code you publish is visible to everyone and becomes a reflection of your expertise. This process encourages you to think and act like an engineer, helping you shape and strengthen your engineering mindset.

I have many personal projects in my code inventory that I still re-use in my daily work. I’m passionate about challenging my skills and implementing ideas I find interesting, even if someone else has already created a widely-used, popular project. There’s immense satisfaction in saying, ‘Look, Spring is an outstanding framework, but I’ve created my own minimalistic dependency injection library.’ It’s rewarding to have walked the same rough path that those industry-leading projects once did. This experience helps me better understand the challenges, think more creatively, and develop new ideas based on existing ones.

Consistent Hashing Explained

As the size of the data to be stored or the operational workload on the system increases, it becomes impossible to handle this amount with a single physical hardware, and the need for managing the load across multiple hardware components, i.e., horizontal scaling, arises. In addition, distributed data or workload shared across multiple components in a distributed system should be accessible by clients with minimal effort. For instance, in a NoSql database, accessing randomly distributed data on multiple nodes would require querying each system component one by one, resulting in a linear time-complexity in the number of added hardware to the discovery operation. This is not a desired approach. One solution to optimize the linear characteristic of the discovery operation is to introduce an external indexing component which tracks the nodes on which the data reside but it is not the only solution. Functions that yield the same result for a specific input can eliminate the need for external component usage for indexing and discovery. For example, hash functions can be used for this purpose.

Hash functions have the property of consistently mapping a random number of elements in the input space to a finite output space, where these elements of the set are called buckets. In other words, for each input x, hash(x) = y, the number of elements in the function’s result set is determined. Using this property, for example, we can map the keys of data sets in a cache or database to the elements of the hash function’s result set. Then, in the next step, we can reduce the resulting value to the desired number of nodes without breaking the mapping consistency by applying the modulus operation. As an example, let A = {1a24d21, c12d422, …, 1e14e124a21} be a key set for which a hash function’s value set is defined such that h(x) = y, for x ∈ A, y = {1, 2, …, 1024}, meaning that for each element in set A, the hash function returns a value up to 1024. If the data to be stored is distributed across four nodes, by applying the modulus operation to the result set, z = y mod 4, we obtain the desired node index, and h(“AB56CD”) = 5, 5 mod 4 = 1, indicating node number 1.

The above example is actually one approach to implement consistent hashing by using hash and modulus functions. If we visualize this implementation, we can imagine that the elements of the hash result set are arranged on a circle and the circle is divided by the nodes which own the before-coming elements:

Each differently colored section in the ring defines the key range managed by the nodes, and if we continue moving on the circle beyond the last node area, just like in the modulus operation, we return to the beginning, the first node.

Notice that for a key in the key space, the hash function gives the same output regardless of the number of nodes. If there is a decrease in the number of nodes, the area of the neighboring node responsible for the area of the departed node (in the example, node 4) is merged, eliminating the need for any changes in the data sets managed by the other system components. This way, the impact caused by the departed node does not spread throughout the system and remains local.

Virtual Components

However, in the load distribution mentioned above, the neighboring system component, node 3, may end up with a heavier load during the redistribution of data because it needs to take over the data of the offline component, node 4. To overcome this problem, virtual components are used in the ring, and the distribution of data on the components is rebalanced.

Similarly, if ‘node 4’ leaves the system due to a failure, the data managed by node 4 is more evenly distributed among the remaining three components:

Virtual components are an effective method for balancing the load distribution, but depending on the content of the data, they may not always be sufficient. Therefore, sometimes hotspots and imbalances can occur on the ring. These hotspots are undesirable as they create load imbalances. Despite the addition of virtual components, if there is still an imbalance in the load distribution, a variant of consistent hashing called ‘bounded-load’ can be considered as a solution with an upper limit.

Bounded-Load Hash Ring

In this variant, the capacity upper limits of the ring’s components are predetermined, and if the load exceeds this limit, the incoming load is transferred to the next node with available capacity. This prevents hotspot formation on the nodes. Although this method puts pressure on the ring to prevent hotspot formation, it introduces additional cost when redistributing the data. The decision to use this variant can be made when imbalance is observed in the production load distribution.

In conclusion…

Consistent Hash Ring is a load distribution and balancing technique commonly encountered in database and cache implementations. This method allows us to horizontally scale the data across multiple components and increases fault tolerance as it only requires redistributing the affected data set among the remaining components in case of a node failure. However, depending on the changing number of nodes and the content of the data, the balanced distribution of the load on the nodes can be disrupted by creating hotspots. In such cases, another variant of Consistent Hashing called bounded-load can be used to limit and transfer the overloaded load to the next node.

References

1. https://ai.googleblog.com/2017/04/consistent-hashing-with-bounded-loads.html?m=1
2. http://highscalability.com/blog/2023/2/22/consistent-hashing-algorithm.html
3. https://web.stanford.edu/class/cs168/l/l1.pdf

In this article I will demonstrate an example service implementation by using Spring Boot and Bucket4j. The article contains only the core components to keep it simple. The example project, we will walk through below, can be seen >here.

Overview

A token bucket is a container of tokens of which capacity or budget is limited for a certain amount of time. For incoming requests, tokens will be taken out of the bucket while refilling it again after a predefined period. If the tokens in bucket are exhausted, the service rejects subsequent requests so long as the bucket is refilled and has capacity again. To have throughput under control, it provides a limited number of tokens for a period which prevents users from surpassing limits of available resources what consequently might lead up to increased latency in service. You may have noticed that a token bucket algorithm is quite similar to the fixed window throttling mechanism. Indeed, the difference between the token bucket and a fixed window rate limiter is slight. A fixed window rate limiter allows a strict throughput within a predefined period. However, token buckets also will enable you to control how fast a bucket can be refilled. The token bucket will act as a fixed window throttler if you keep the same fixed refill rate. One thing that neither a token bucket nor a fixed window rate-limiter cannot prevent is the burst (In a fixed-window rate limiter, if the request-burst overlaps the ending and beginning of two windows, the effect will even look worse. The sliding window rate limiter improves weakness of the fixed-window rate limiter by taking the previous window’s state into account.). Nevertheless, you can convert a token bucket into a leaky bucket while adding a fine-grained throughput controller, e.g., a maximum of one hundred requests per second whereas the bucket’s capacity has control over a more extended period.

Distributed Token Bucket with Bucket4j

In the following example, I use Spring Boot framework and Redis to demonstrate a realistic cloud service implementation. The bucket state will be maintained in a database so that application instances can access this shared state and evaluate it every time as a request is being handled in the container. If your use case doesn’t require persistence, for example, what you need is to protect resource exhaustion on a single instance, you may want to omit the database option. However, suppose your use case requires tracking overall resource usage and implementing an enforcement mechanism, e.g., a quota management instance. In that case, you should evaluate persistence options to store the bucket state.

Implementation as a Spring Boot Service

Rate limiting should preferably operate before the business logic layer picks up the request to keep the domain-relevant implementation simple and lean. In Spring-based applications, it can be implemented, for instance, as a handler interceptor, which pre-and-post processes the requests. The interceptor verifies the access limits by delegating the call to the rate limiter component. Once the limit is exceeded, the rate limiter and the interceptor, respectively, reject subsequent requests with HTTP 429 “Too many requests” immediately - and it is also a good practice to include a Retry-After header to let clients know when they should come back for the next request:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public boolean preHandle(
    HttpServletRequest request,
    HttpServletResponse response,
    Object handler) {

    Map<String, String> pathVars = (Map<String, String>)
       request.getAttribute(HandlerMapping.URI_TEMPLATE_VARIABLES_ATTRIBUTE);

    if (!rateLimiter.tryAccess(pathVars.get(USER_ID))) {
        response.setStatus(TOO_MANY_REQUEST);
        response.setHeader(RETRY_AFTER, IN_300_SECS);
        return false;
    }
    return true;
}

The RateLimiter service below provides its clients with a “tryAccess()” method, of which call queries the underlying bucket with a key. Since we maintain a token bucket per key, e.g., in our scenario, a user identifier, we need to pass it to the proxy manager so that the corresponding token bucket can be looked up in the database:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public class RateLimiter {
    private final RedissonBasedProxyManager redissonBasedProxyManager;
    private final BucketConfiguration bucketConfiguration;

    public RateLimiter(RedissonBasedProxyManager redissonBasedProxyManager,
                       BucketConfiguration bucketConfiguration) {
        this.redissonBasedProxyManager = redissonBasedProxyManager;
        this.bucketConfiguration = bucketConfiguration;
    }

    public boolean tryAccess(String key) {
        return redissonBasedProxyManager
                .builder()
                .build(key, bucketConfiguration)
                .tryConsume(1);
    }
}

RedissonBasedProxyManager ➋ is the proxy implementation for Redis-backed token buckets, that is provided by Bucket4j. It will store by BucketConfiguration ➌ configured token bucket’s state in Redis. Both components are Spring Beans and injected to RateLimiter, which is also managed by IoC container:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
@EnableWebMvc
@Configuration
@EnableCaching
public class AppConfig implements WebMvcConfigurer {

    @Bean
    public RateLimiter rateLimiter() throws IOException {
        return new RateLimiter(proxyManager(), bucketConfiguration());
    }

    @Bean(destroyMethod = "shutdown")
    public ConnectionManager redissonConnectionManager() throws IOException {
        File resourceURL = ResourceUtils.getFile("classpath:redis.yml");
        Config config = Config.fromYAML(resourceURL);
        return ConfigSupport.createConnectionManager(config);
    }

    @Bean
    public RedissonBasedProxyManager proxyManager() throws IOException {
        CommandSyncService commandSyncService = 
            new CommandSyncService(redissonConnectionManager());
        return new RedissonBasedProxyManager(commandSyncService,
                ClientSideConfig.getDefault(),
                Duration.ofMinutes(10));
    }

    @Bean
    public BucketConfiguration bucketConfiguration() {
        return BucketConfiguration
            .builder()
            .addLimit(Bandwidth.simple(2, Duration.ofSeconds(1)).withInitialTokens(2))
            .build();
    }
}

Above, the bucket configuration instantiates a Bucket4j token bucket configuration, which has the bandwidth of two tokens, and it is refilled every two seconds while being consumed by one token with every request.

Conclusion

Even though the general approach to implementing a bucket token is by reducing buckets by one token for each request, your use case may require removing more than one token depending on API group, for instance, to apply stricter limits to requests on resource-consuming APIs. However, this might introduce more sophisticated policy control requirements while considering resource requirements of different APIs, different types of user contracts, central authority of bucket configurations, etc. So, depending on the problem you are trying to solve, some contract-based quota management vs. throttling to protect server-side resources, the architecture can be enhanced with additional components. Token bucket is quite simple but handy algorithm that can be used to implement for throttling requests in web services to protect server-side resources while enabling a fair resource sharing by limiting the noisy neighbors. With the F/OSS frameworks like Bucket4j, it is also quite straightforward to integrate with existing service architecture. You can also leverage it to implement e.g. quota management according to some license-based policies, which are incorporated with your business requirements. One thing that it cannot prevent is the request burst. Yet you can streamline the implementation with additional limitation e.g. maximum request per time unit, what would then behave like a leaky bucket in a sense.

Don’t mix the purpose

Having a clear purpose for writing would keep your composition lean and cohesive. For instance, reference documentation is a guide to the code of which goal is to explain its usage of it, and it should remain as a reference document without attempting to convey more information than its intent at the same time. Mostly, readers have clear goals as they’re seeking through documentation, such as knowing how to use an API, how to integrate a library, how authentication works, and so on. So, we should give them what they need. State the purpose of the documentation at the beginning of the text clearly to align expectations with your audience.

Before you start writing, you can ask questions yourselves like, “why am I writing this?”, “What is the purpose of it?” to nail the right documentation type. Do you want to explain the usage of the source code? Then what you need is reference documentation. A step-by-step guide to accomplish a task? It sounds like a tutorial. Is it about architecture, the interaction of sub-systems, etc.? It sounds like a design document. The important thing is not to meld them in a single pot.

Know your Audience

I noticed engineers’ tendency to easily take it for granted that the audience must be at the same knowledge and experience level. As a result, they automatically take shortcuts while explaining complex topics. This impatience attitude may cause readers to lose focus as they can’t follow the subject due to a potential level mismatch. The other way around is also problematic. The text becomes quickly boring for advanced readers if written at the novice level. So, it is always a good idea to scope the level of readers in the introduction section and give a hint about the level of the content at the beginning of the document as prerequisites.

Maintaining Documentation

Unmaintained, abandoned-look documentation will be quickly discarded by people faster than unmaintained source code. There are a few reasons why engineers have absolutely no understanding of outdated or broken documentations. First, we are eager to see the source code. Reading source code is more intuitive to us, and the code constitutes a source of truth. Second, we have strong prejudices about the currency of documentations. Documentations will be skimmed through briefly, and the first impression is vital for the fate of the text. Any broken link, imprecision in text, and overcomplicated diagrams may lead to them being abandoned faster than you think. Thus, it is always a good idea to keep your documentation up to date and let your readers know that your documentation is regularly updated by adding freshness date, revision, etc., marker.

Location

It is also wise to put your documentation under version control and treat them as source code. Creating pull requests for changes and following the already entrenched software review process, etc., would certainly help improve the quality assurance in the first place. If you need to add diagrams to your documentation, you can consider using “diagram as code” tools like Plant UML to bring them under version control. However, some documentation types are not necessarily that technical as they don’t relate to implementation directly but to some design discussions or high-level project discussions. I would recommend separating such documentation from the project’s base and hiding it from our audience for clarity.

When not write Documentation

Before actual implementation begins, there are activities like high-level project meetings and commitment planning where the capacity requirements and business priorities will be explored. Sometimes, we must deliver rough estimates at this level that will be considered in the decision-making process, e.g., while sequencing the milestones and defining roadmaps. Therefore, it might be wise to take quick notes from our discussions with technical leads to track the path down to our decisions and not invest so much time into a writing activity because it might not be apparent at this stage if the project is officially planned for the next quarter, year, etc. So, I tend to put my notes into informal wiki pages to make the outcome from high-level project meetings accountable of which pieces I re-use in requirements analysis later.

Conclusion

Writing documentation is an essential part of our job and engineering activity. We create documentation for different purposes, including sharing knowledge, creating historical records for our decisions, helping our clients use our products, and so on. Writing documentation is a long-term investment but certainly not a one-time. Documentations need to be maintained as software evolves. To keep them consistent and cohesive, they should serve a single purpose and be aligned with our target audience’s experience and knowledge level. Follow the same review process in software development and put the documentations right next to source code under version control. So, by leveraging entrenched techniques, we can also ensure quality assurance for them.

1
2
3
4
5
6
7
8
9
10
11
12
// ListenSIG listens to SIGWINCH syscall to react on window size changes.
func (w *Window) ListenSIG() {
  go func() {
    for {
      c := make(chan os.Signal, 1)
      signal.Notify(c, syscall.SIGWINCH)
      // Block until a signal is received.
      <-c
      w.Render()
    }
  }()
}

In the example above, I create a new channel to catch the system calls within a go routine. Since the current thread gets blocked and I don’t want whole application to stop while while listening to signals, I put the signal handling code into its own gorouting. By doing so, my code is able to listen to window size change signals and call Render() function of my application’s window infinitely while processing other tasks.

Another way to implement a similar feature is by polling the current terminal window size. I don’t think, however, that this approach would be as efficient as the former one, if you are not able to take signal-handler-approach otherwise,

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
// Private types
type screenSize struct {
  Row    uint16
  Col    uint16
  Xpixel uint16
  Ypixel uint16
}

func GetScreenSize() (uint16, uint16) {
  ws := new(screenSize)
  retCode, _, errno := syscall.Syscall(syscall.SYS_IOCTL,
    uintptr(syscall.Stdin),
    uintptr(syscall.TIOCGWINSZ),
    uintptr(unsafe.Pointer(ws)))

  if int(retCode) == -1 {
    panic(errno)
  }
  return ws.Row, ws.Col
}

The GetScreenSize function sends a system call to Ioctls for terminals and serial lines to find out the current screen size of the terminal, by passing the TIOCGWINSZ. The return value will be stored in an struct. This way, you can determine the current terminal window size and repeat this call, for instance, every a few seconds to capture the window size changes.

Before we get started with OAuth, I briefly want to brush up on the topic first, “Authentication, Authorization and Access Control”. Authentication verifies your identity. It is the same procedure if you show your ID to authorities so that they are able to know who they are talking to. Authentication by Username/Password pair (and along with 2FA) is a broadly adopted method, today. Authorization is there to ensure if an access is authorized to the requestor, who has already been authenticated, for instance if you possess a driver license you are authorized to drive a car, while access control does manage the permissions/privileges.

OAuth 2.0 in a Nutshell

OAuth 2.0 is an authorization protocol standardized under RFC 6749 within the IETF as an open standard, of which purpose is to specify user-and-client authorization on protected resources without sharing their credentials with each other. The roles defined in OAuth are:

Resource owner, that is the end-user who owns resources of interest, that is hosted by resource server, the client, the application which claims access on resource owner’s (user’s) protected resources and perform some operations on behalf of the user and authorization server which manages user and client authentication and authorization by exchanging user credentials with authorization code and access tokens. The authorization workflow is initiated by the client, that is the application requesting access on resource owner’s resources on behalf of a user, e.g a mobile app. Resource server is the server which hosts the protected resources. It only accepts the requests with a valid access token. The authorization server is the one which issues access tokens (and authorization codes depending on the grant type) to the clients after a successful authentication.

Figure - 1: OAuth 2.0 Workflow with grant type “authorization code”

Access Token

Access tokens are credentials, that are issued to clients by authorization server, allowing them to access protected resources. Access tokens are valid till they expire and may be effective in a pre-defined scope, in which the client is allowed to operate e.g read-scope, read-write scope, private scope, etc. By using access tokens in client and server communication, we eliminate the need of sharing resource owner’s credentials, so client applications like mobile apps do not need to memorize user’s credentials, at all.

The other token type is the refresh token. Refresh token is only used to obtain a new access token before the access token expires. Once a client application is authorized, there is no need to re-authenticate the user, everytime the access token expires if it has a refresh token. In this case, the client may use the refresh token that is returned from the authorization server along with the access token to obtain a new access token from the authorization server.

Authorization Grants

In OAuth 2.0 world, the main motivation is, “Do not share user’s credentials with clients”. The application, that is the client, may be a native one to OS, or some JavaScript application that is run by browser. Depending on the degree of the trust between client and user, the client application may ask user’s credentials to obtain access token from authorization server without having an intermediate step as grant type “Resource Owner Password Credentials”. It requires, however, a higher degree of trust. Although the client is allowed to access user credentials over a short period of time, till it receives an access token from the authorization server.

On the other hand, the client might be another web service, and in this case the user will be redirected to the authorization server with a client id, an optional scope parameter and a redirection URI so that the user is able to authenticate on their own. A real-life example for this authentication flow is “Facebook integration” on Twitter. Twitter, the client, needs access to protected resources to post your recent tweets on your Facebook timeline. After a successful authentication process against Authorization Server, Facebook, the request will be redirected to the clients redirection URI (to Twitter) with an authorization code with which the client can request an access token from Authorization Server. In this “authorization code” grant, the client access to the user credentials is not permissible.

There are two more authorization grants, the “implicit” and the “client credentials”. In the implicit workflow, the user-agent has to be redirected to the client with an access token, instead of using an auth code and without requiring the client to get authenticated with an auth code. Yor are probably familiar with this grant type from JavaScript web applications. Moreover, authorization-grant with “client credentials” requires the client to authenticate itself with its own credentials. This type of authorization grant is useful, in case, the client is the resource owner and defines the scope of access.

Scopes

Scope defines the boundaries of the authorization request. The authorisation server may enforce the clients to specify the scope while requesting access token in which scope the access token should be effective. RFC 6749 3.3 Even though scopes are optional, they are essential in workflows and we will revisit them later.

In the next section, we are going to integrate these foundations with implementation so that resource owners are able to access their resources while unauthorized access can be denied. To do this, we use Spring framework which provides an annotation-based programming model to incorporate OAuth 2.0 concepts with services declaratively.

Building the Backend

So far we have covered the groundwork about OAuth 2.0, that is required to understand the concepts which we use to build our authorization and authentication backend. Next step, we are going to start creating the components like Authorization Server, Resource Server, and so on. The backend, I am giving as example here, is part of a hypothetical book webshop so as to store book reviews. It means, there will be users who require access to write some reviews while other users will only need read access to view the reviews.

The sample application, we are building here, is a Spring Boot Application so we can start the container either by running the Spring Boot Maven plugin in the command line or as Java executable by running the main method, e.g, in an IDE - another approach would be by hitting java jar command if the application has already been packaged in JAR file. Moreover, the application is backed by a MySQL database so that the user credentials can be persisted. I am going to set up a docker container environment to start the entire back-end on my local computer. Dockerization will speed up “development and test cycle” and once we decide to deploy our back-end, it is much easier to roll the services out onto a container orchestration platform like Mesos or Kubernetes.

To build the backend, we will create a new Maven project from scratch while adding Spring Boot parent into the project’s POM which ensures the right versions of dependencies get included. For the sake of ease, I will create a single project which includes both the Resource and the Authorization Server in the same application, but in production, you may want to split them into two separate services, depending on the scale. For this purpose, I used the Maven simple project archetype and the files are organized in classical Maven project structure, i.e we have the Java packages in src/main/java and resources like configurations, etc. in src/main/resources source directories.

Figure - 2 : Project’s structure

The Figure 2 demonstrates the project structure we will work on throughout this article. I organized the classes in packages as follows:

1	io.ryos.auth

is for Spring Boot application classes and configurations.

1	io.ryos.dao

contains the classes for persistence layer, e.g entities, repositories (of Data Access Layer).

1	io.ryos.data

has some value objects like UserProfile as a representation of the user file.

1	io.ryos.resources

is where REST resources are located and the resources source directory to keep classpath files like configurations, properties-files, etc. The project’s POM resides in the root directory along with docker-compose.yml. The POM includes the Spring Boot’s starter parent:

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>${spring.boot.version}</version>
        <relativePath />
    </parent>

Example - 3 : Parent POM.

We will also need the following dependencies to enable the Spring Framework in the project and some more dependencies mostly pertaining to Java persistence and MySQL driver:

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.security.oauth</groupId>
            <artifactId>spring-security-oauth2</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
        </dependency>
        <dependency>
            <groupId>javax.persistence</groupId>
            <artifactId>persistence-api</artifactId>
        </dependency>
    
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

Example - 4 : Project’s POM file.

Note that, the first annotation, ➊

1	@SpringBootApplication

, enables Spring Boot application and it takes an attribute, “scanBasePackages” with a list of package names in which Spring framework has to search for annotated Spring components and instantiate them. ➋ The

1	@EnableJpaRepositories

is similar to @SpringBootApplication. It enables the Java Persistence (JPA), that is required to build the persistence layer. ➌ The third annotation is the

1	@EnableTransactionManagement

which enables annotation-based Java transaction management (JTA). And the last annotation, ➍ @PropertySource defines the name of the configuration file in the classpath:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
 
@SpringBootApplication(scanBasePackages={"io.ryos"}) ➊
@EnableJpaRepositories(basePackages={"io.ryos"}) ➋
@EnableTransactionManagement ➌
@PropertySource("version.properties") ➍
public class Application {
 
    private static final String CONN_URL = 
        "jdbc:mysql://localhost:3306/ryos_auth?useUnicode=true&characterEncoding=UTF-8";
        
    private static final String SQL_DIALECT = 
        "org.hibernate.dialect.MySQL5InnoDBDialect";
 
    @Qualifier("dataSource") ➎
    @Autowired
    private DataSource dataSource;
    
    @Bean
    public DataSource dataSource() { ➏
        DriverManagerDataSource dataSource = new DriverManagerDataSource();
        dataSource.setDriverClassName("com.mysql.jdbc.Driver");
        dataSource.setUrl(CONN_URL);
        dataSource.setUsername("root");
        dataSource.setPassword("p@ssw0rd");
        return dataSource;
    }
    
    private Properties jpaProperties() { ➐
        Properties properties = new Properties();
        properties.put("hibernate.dialect", SQL_DIALECT); 
        properties.put("hibernate.show_sql", "true");
        return properties;  
    }
    
    @Bean
    public LocalContainerEntityManagerFactoryBean entityManagerFactory() { ➑
        HibernateJpaVendorAdapter vendorAdapter = new HibernateJpaVendorAdapter();
        vendorAdapter.setDatabase(Database.MYSQL);
        vendorAdapter.setGenerateDdl(true);
        vendorAdapter.setShowSql(true);
        LocalContainerEntityManagerFactoryBean factory = 
            new LocalContainerEntityManagerFactoryBean();
        factory.setJpaVendorAdapter(vendorAdapter);
        factory.setPackagesToScan("io.ryos.dao.entity");
        factory.setDataSource(dataSource());
        factory.setJpaProperties(jpaProperties());
        return factory;
    }
    
    public static void main(String[] args) { ➒
        SpringApplication.run(Application.class, args);
    }
}
 

Example - 5 : Application class.

With the “dataSource” bean configuration ➎ a data source is configured, that is how the application does reach the database ➏. Spring makes the data source class-wide available. ➐ jpaProperties is a helper method which provides required properties for JPA. ➑ “entityManagerFactory” method is a Java-based bean configuration, that is employed to instantiate EntityManagerFactory instance, that is the gateway to the persistence context where the entities and their life-cycles are managed. Finally, ➒ is the main method to start the Spring Boot application.

The first component we create is the Authorization Server. I will put all application components into a single Spring Boot project for the sake of ease. But, in a real-life application, you probably need to consider to separate the applications, the authorization and resource server. But, before we begin with Authorization and Resource Server, first, we will set up web security. Fortunately, Spring provides configurer adapter classes that need to be inherited while implementing

1	configure()

methods.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
 
@Configuration
public class WebSecurityConfiguration extends WebSecurityConfigurerAdapter {
 
    @Autowired
    @Qualifier("userRepositoryService")
    private UserDetailsService userDetailsService; ➊
    
    @Override
    protected void configure(AuthenticationManagerBuilder auth)
            throws Exception {
        auth.userDetailsService(userDetailsService); ➋
    }
    
    @Override
    @Bean(name="authenticationManagerBean")
    public AuthenticationManager authenticationManagerBean()
            throws Exception {
        return super.authenticationManagerBean(); ➌
    }
    
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.csrf().disable() ➍
                .authorizeRequests().antMatchers("/login").permitAll().and() ➎
                .authorizeRequests().anyRequest().hasRole("USER"); ➏
    }
}
 

➊ Please note that, we inject userDetailsService, the service component, that is used to access database to read user data. ➋ The userDetailsServer reference is passed to the Authentication Manager so that it is able to know how to access user database. ➌ We create an authentication manager bean. With ➍, we configure web security and its boundaries. By default, the security rules apply to all requests, but we can also define matchers to tell the framework on which resources what kind of rules are going to be effective in runtime e.g in ➎ and ➏ we permit all request targeting /login while requiring to have the role “USER”.

Authorization Server

As we saw earlier, authorization server is the component where tokens are issued to the clients. Implementing an Authorization Server with Spring, is simply to add another Bean configuration into the project. The bean configuration for the authorization server extends AuthorizationServer- ConfigurerAdapter and is annotated with @EnableAuthorizationServer which is necessary to enable the authorization server component. There are two other Spring components get injected via @Autowired, the authenticationManager and the userDetailsService. The latter is the repository and DAO indicating how Spring framework accesses the user data in database and the former is authenticationManager.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
 
@Configuration
@EnableAuthorizationServer
public class AuthorizationServerConfiguration extends AuthorizationServerConfigurerAdapter {
 
    @Autowired
    @Qualifier("authenticationManagerBean")
    private AuthenticationManager authenticationManager;
    
    @Autowired
    @Qualifier("userRepositoryService")
    private UserDetailsService userDetailsService;
    
    @Override
    public void configure(AuthorizationServerSecurityConfigurer oauthServer) throws Exception {
        oauthServer.tokenKeyAccess("permitAll()").checkTokenAccess("isAuthenticated()"); ➊
    }
    
    @Override
    public void configure(ClientDetailsServiceConfigurer clients) throws Exception {
                
        clients.inMemory() ➋
                .withClient("ryosApp") ➌
                .secret("abc123")
                .scopes("world") ➍
                .authorizedGrantTypes("password", "refresh_token") ➎
                .resourceIds("resource");
    }
    
    @Override
    public void configure(AuthorizationServerEndpointsConfigurer endpoints)
            throws Exception {
        endpoints.tokenStore(tokenStore()) ➏
                .authenticationManager(authenticationManager)
                .userDetailsService(userDetailsService);
    }
    
    @Bean
    public TokenStore tokenStore() {
        return new InMemoryTokenStore(); ➐
    }
}
 

The bean configuration for the authorization server extends an adapter class, “AuthorizationServer- ConfigurerAdapter” and it is annotated with @EnableAuthorizationServer which enables the authorization server throughout the application. There are two other Spring components which get injected by @Autowired, the authenticationManager and the userDetailsService. The latter is the instance to the repository and DAO which helps us in accessing the user data and the former is authenticationManager.

Let us stick with the AuthenticationManager a bit, first, the interface with the authenticate() method. The implementation of AuthenticationManager, the ProviderManager is responsible to authenticate the request by iterating over authentication providers. It is technically hooked up to the security servlet filters and does process requests before they reach any REST resources. If AuthenticationManager is successful, it returns a non-null response that indicates that the request is authorized. If none of the providers returns a non-null response, then the request will end up with an AuthorizationException.

In “AuthorizationServerConfiguration”, we define three overloaded configure() methods, ➊ taking a AuthorizationServerSecurityConfigurer as parameter. It configures security rules for Authorization Server, for instance, permit all requests to the endpoint through which access tokens are issued while requiring authorized access on the token endpoint. In the second configure method, ➋ we set up the Client Details Service - just like user details service, it is responsible for providing information about the client. We use in our example an in-memory service with a single static client ➌ “ryos” and its secret, ➍ with read and write scopes and grant types ➎ “password” and “refresh_token”. With ➏, we hand the token store, authentication manager, and the user details service over to the authentication server endpoint configurer. ➐ As token store, we use also an in-memory store provided by the framework.

Resource Server

It is now time to set up the resource server. In resource server configuration, we do not have that much. The configuration bean is annotated with @EnableResourceServer while extending ResourceServer- ConfigurerAdapter class, provided by the framework. The bean configuration overrides the configure method and defines the resource id.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
 
@Configuration
@EnableResourceServer
public class ResourcesServerConfiguration extends ResourceServerConfigurerAdapter {
 
    @Override
    public void configure(ResourceServerSecurityConfigurer resources) {
        resources.resourceId("resource");
    }
    
    @Override
    public void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests().antMatchers("/version").authenticated();
    }
}
 

In the overloaded configure()- method which takes the HttpSecurity parameter, HttpSecurity instance is configured while requiring the requests having authorized on matching resource “/version” and having authenticated.

The REST Resource

The API’s REST resource which is handling the review requests looks like as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
 
@Controller
@RequestMapping("/reviews") ➊
public class HelloResource {
 
    @Autowired
    private BookReviewService bookReviewService; ➋
 
    @RequestMapping(method = RequestMethod.GET) 
    public @ResponseBody
    ResponseEntity showReview(
        final @QueryParam("isbn") String isbn
        final Principal principal) { ➌
        return bookReviewService.getReview(isbn);
    }
}
 

➊ The REST resource handler accepts GET requests targeting to

1

/reviews

API endpoint. The response object that is returned from the BookReviewService ➋ of which instance is injected to the resource by Spring’s IoC container. ➌ The resource handler method showReview does, in addition, declare an argument,

1

Principal

which contains the security context, about that we talk later and an HTTP query parameter “isbn” ISBN number of the book.

Testing

We can test the authorization server by making requests, for instance, with cURL and ask for an access token as well as refresh token:

1
2
3
4
curl ryosApp:abc123@localhost:9000/oauth/token \
   -d username=bagdemir  \
   -d password=123456 \
   -d grant_type=password

the response,

1
2
3
4
5
6
7
{
    "access_token": "93e8733e-022b-4387-abf5-79974323e7f5",
    "token_type": "bearer",
    "refresh_token": "0fbfc23c-5f1d-4c13-afbd-7c2144122ed2",
    "expires_in": 43199,
    "scope": "read write"
} 

Once we acquired the access token, we now are able to access protected resources. But first, let me try to call the REST resource with the access token:

1
curl -X GET http://localhost:9000/version

and the result,

1
2
3
4
{
    "error": "unauthorized",
    "error_description": "Full authentication is required to access this resource"
}

As you can see, we may not access the protected resource without providing an access token. In the next example request, we provide the access token in the Authorization header as bearer:

1
2
 curl -X GET http://localhost:9000/version \
    -H "Authorization: Bearer 32f3f08e-e124-444b-bfc4-55bd559b44a7"

and the result,

1
2
3
4
5
{
    "versionInfo": 1,
    "buildInfo": "1",
    "releaseDateStr": "12.04.2018"
}

Just as the slash separated set of elements is useful for representing a tree, so a set of names and equally significant parameter can represent a space more like a (possible sparse) matrix.

Although the RFC3986 does touch upon matrix parameters as sub-components of path segments and the delimiters “;” and “=“ are defined as “reserved” characters, the RFC is reluctant to call them “matrix” parameters. The reason is, matrix URIs were still in proposal state as the RFC3986 was published and its status has not been changed since then. In this blog, we will take a closer look at a few examples of matrix URLs and how they are incorporated in higher-level concepts like Java API for RESTful Services. Let us begin with a simple example:

1
2
/foo;version=1/manifest
/foo;version=2/manifest

According to the RFC, the semantics of matrix URIs - and how they qualify a particular path segment within a hierarchical path is left to the implementation. In the example above, the path down to the manifest file is branching depending on the version parameter. Identification of the resource, manifest, might vary with different values of version parameter, but it might also stay the same. It is up to the application.

Matrix URIs gain inevitably complexity with the number of parameters, they define,

this time, each path segment has its own list of qualifying matrix parameter, extending the dimension of the hierarchical system. The additional vector might be compelling for creators of new specifications and implementators thereof with the conceptual building-blocks of a higher-layer domain, that relies on matrix URIs. One good example for that higher-level domain is the JAX-RS specification, that is Java API for RESTful web services and @MatrixParam annotation, that makes matrix parameters first-class entities. In the following example, JAX RS’ @MatrixParam annotation is used to extract the value of a matrix parameter from URIs:

1
2
3
4
5
6
7
8
9
10
11
12
@Service
@Path("/")
public class MatrixResource {

  @GET
  @Path("/status/ping")
  @Produces("text/plain")
  public String ping(@MatrixParam("name") String name) {
    return String.format("matrix variable name=%s", name);
  }
}

The resource handler method ping() accepts the requests targetting the /status/ping endpoint while declaring a matrix parameter “name” in the example above. If you you send an HTTP GET request to the /status/ping endpoint, the response will be:

1
2
➜ curl -X GET http://localhost:8080/status/ping
matrix parameter name=null

if no matrix parameter is provided, the value is null, as expected. Another request with a matrix parameter ;name=bar,

1
2
➜ curl -X GET 'http://localhost:8080/status/ping;name=bar'
matrix parameter name=bar

the matrix param has the value “bar”. But, in the following example the value of the matrix parameter will be null, that might be confusing:

1
2
➜ curl -X GET 'http://localhost:8080/status;name=bar/ping'
matrix parameter name=null

The reason for this is, that the @MatrixParam annotation “refers to a name of a matrix parameter that resides in the last matched path segment of the Path-annotated Java structure that injects the value of the matrix parameter”, as JEE/EE4J JAX-RS API outlines. The request handler equipped with @MatrixParam is not capable to resolve the matrix parameter of intermediate path segments within the same request handler. This would make the JAX-RS specification look congruent with the RFC-3986. Nevertheless, the JAX-RS implementations remove this gap by opening up the access to matrix parameters via PathSegments:

1
2
3
4
5
6
7
8
9
10
11
12
13
@Service
@Path("/")
public class MatrixResource {

  @GET
  @Path("/{status}/ping")
  @Produces("text/plain")
  public String ping(@PathParam("status") PathSegment status) {
    MultivaluedMap<String, String> matrixParameters = status.getMatrixParameters();
    String nameMatrixFromStatus = matrixParameters.getFirst("name");
    return String.format("matrix variable name=%s", nameMatrixFromStatus);
  }
}

this time, the value of the matrix parameter is gathered from the PathSegment instance, that is defined with the path template {status}. Spring developers might have noticed this gap, because Spring’s non-JAX-RS-conform annotations solve this problem via partial binding:

1
2
3
4
5
6
7
8
9
10
@RestController
public class MatrixResource {

  @RequestMapping(value="/{status}/ping", method=RequestMethod.GET)
  public String pong(
      @PathVariable("status") String status,
      @MatrixVariable(name="name", pathVar="status", required=false) String name) {
    return String.format("matrix variable name=%s", name);
  }
}

In Spring Boot, the “scope” of the matrix variable can be defined with “pathVar” attribute, explicitly, in contrast to JAX-RS standard annotations [See Note 1]. Still, this is a very good example for limitations of Java annotations if they are used to describe slightly complex structures. The idea of injecting data into class fields, constructors and method parameters is common in Java stack and has its charm, but as data structures are getting more dimensions like matrix URIs, specifications using annotations will be clumsy.

One might ask, “why do not we simply use query parameters instead of matrix parameters?”. Query parameters apply to the entire path. The URL with matrix parameters can be rewritten as follows:

1
2
/mylib;version=3/manifest;version=2/?format=json
/mylib/manifest/?format=json&mylib_version=3&manifest_version=2

The URI with query parameters has less clarity and the query parameters need additional information for namespacing so as to resolve the ambiguity.

Conclusion

Although the matrix URIs were just a design idea from Tim-Bernes Lee, they are widely adopted in web services landscape - especially web services in RESTful fashion. The frameworks implementing the JAX-RS does support matrix parameters, albeit their API specification might not look congruent with the original idea, but implementations thereof e.g Jersey enable full access to matrix parameters in arbitrary path segments. Spring Boot variant does equip non-JAX-RS

1	@MatrixVariable

annotation with additional attributes which allows to define the context of matrix variable.

References

1. https://www.w3.org/DesignIssues/MatrixURIs.html, Tim Berners-Lee
2. https://stackoverflow.com/questions/2048121/url-matrix-parameters-vs-query-parameters
3. https://jakarta.ee/specifications/restful-ws/3.0/restful-ws-spec-3.0-M1.pdf
4. https://tools.ietf.org/html/rfc3986#section-3.3
5. https://forum.raml.org/t/rfc3986-matrix-variables/73
6. https://jakarta.ee/specifications/restful-ws/3.0/restful-ws-spec-3.0-M1.pdf [PDF]

Notes:

1. The matrix variables are needed to be activated in Spring Boot application:

1
2
3
4
5
6
7
8
9
@Configuration
public class MatrixConfig implements WebMvcConfigurer {
  @Override
  public void configurePathMatch(PathMatchConfigurer configurer) {
    UrlPathHelper urlPathHelper = new UrlPathHelper();
    urlPathHelper.setRemoveSemicolonContent(false);
    configurer.setUrlPathHelper(urlPathHelper);
  }
}

Since the Scenario mode in Rhino simulations is the default one, if you want to enable the DSL mode, you need to change the Runner implementation by adding the @Runner annotation to your Simulation class and passing the ReactiveHttpSimulationRunner to its clazz attribute:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
@Simulation(name = "File Upload Simulation") ❶
@Runner(clazz = ReactiveHttpSimulationRunner.class) ❷
@UserRepository(factory = OAuthUserRepositoryFactoryImpl.class)
public class UploadDSL {

  @Provider(factory = UUIDProvider.class)
  private UUIDProvider uuidProvider;

  @Dsl(name = "Upload File") ❸
  public LoadDsl singleTestDsl() {
    return Start.dsl() ❹
        .run(http("PUT text.txt") ❺
            .header(c -> from(X_REQUEST_ID, "Rhino-" + uuidProvider.take()))
            .header(X_API_KEY, SimulationConfig.getApiKey())
            .auth()
            .endpoint((c) -> "http://foo/" + uuidProvider.take())
            .upload(() -> file("classpath:///test.txt"))
            .put()
            .saveTo("result")); ❻
  }
}

Simulation entity starts with the @Simulation ❶ annotation which marks the class as a load testing entity. To enable the DSL mode, we use @Runner ❷ with the simulation runner implementation, ReactiveHttpSimulationRunner (Default runner is the DefaultSimulationRunner which runs the Scenario methods). DSL methods are marked with @Dsl ❸ with a name which is used in reporting of performance measurements, that is mandatory. The implementation of the DSL method uses chained-style method invocations, starts with

1	Start.dsl()

❹ and followed by runner methods, like run, runIf, runUntil, etc. ❺ Runner methods takes Specs instances as parameters. A Spec describes how a load test action to be performed. The result of execution will be stored in the session with ❻ for the next runners and specs.

You can now run the “File Upload Simulation” with a simple Java application:

1
2
3
  public static void main(String ... args) {
      Simulation.create(PROPS, RhinoDSL.class).start();
  }

The framework will then generate the load according to the DSL.

Load DSL is extensible

Rhino DSL framework is extensible. In addition to the specs which framework provides for you, by the way, you can easily add new spec types and materializers thereof to extend the DSL framework. A spec materializer is a component which takes spec instances as input and creates reactive components.

Simulations might have one or more Dsl methods and each DSL method comprises a set of runner methods. Runner methods takes the Spec instances as parameters and materializes them by using spec materializers.

Let’s have a look at an example spec, SomeSpec which is the spec for executing arbitrary code:

1
2
3
4
5
6
public interface SomeSpec extends Spec {

  Spec as(Function<UserSession, String> function);

  Function<UserSession, String> getFunction();
}

1

as()

method takes an argument of Function<UserSession, String> which is run by the enclosing runner. The Spec implementation is just a simple builder:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
public class SomeSpecImpl extends AbstractSpec implements SomeSpec {

  private Function<UserSession, String> function;

  public SomeSpecImpl(final String measurement) {
    super(Objects.requireNonNull(measurement));
  }

  @Override
  public Spec as(final Function<UserSession, String> function) {
    this.function = Objects.requireNonNull(function);
    return this;
  }

  @Override
  public Function<UserSession, String> getFunction() {
    return function;
  }
}

as Spec instances are holding the information which is needed in materialization process, materializers take the information conveyed by specs and transform them into reactive components. A simple materializer which takes the Spec instance and produces a Mono:

1
2
3
4
5
6
7
8
9
10
11
12
public class SomeSpecMaterializer implements SpecMaterializer<SomeSpec, UserSession> {

  @Override
  public Mono<UserSession> materialize(SomeSpec spec, UserSession userSession) {

    return Mono.just(userSession)
        .flatMap(session -> Mono.fromCallable(() -> {
          var status = spec.getFunction().apply(session);
          return session;
        }));
  }
}

I hid some details about performance measurement in the implementation to keep the example simple. If you want to throw a look into the full implementation of SomeSpecMaterializer, please follow the link.

Now, you can use your new spec in the DSL:

1
2
3
4
5
6
7
8
9
10
11
  @Dsl(name = "Some")
  public LoadDsl singleTestDsl() {
    return Start.dsl()
        .run(some("test") ❶
        .as(session -> {  ❷
            session.add("say", "hello world");
            return "OK";
        }))
        .saveTo("result");
  }
}

1

some()

method ❶ is just a static factory which creates a new SomeSpecImpl intance for convenience. SomeSpec function takes a session object ❷ as parameter. Sessions are contextual objects to store data. For more information about sessions, please follow the link. That’s it. You have just created your first functional Spec component.

Wrap-up

Load DSL is the domain specific language to implement load and performance tests in Rhino. DSL declares how synthetic load is to be generated whereas the scenario methods contain actual implementation of the load generation process. Load DSL is extensible. You can add your own specs and materializers to create new operations. Furthermore, using Load DSL comes at a price. If your tests are getting more complex, your DSL methods will get longer and readability may suffer from long chained method calls. So, you might prefer to use the Scenario mode, instead.

Creating your first project

You can create Rhino projects by using Rhino Archetype. The Maven Archetype project allows developers to create new Rhino performance testing projects from the scratch:

1
2
3
4
5
6
$ mvn archetype:generate \
  -DarchetypeGroupId=io.ryos.rhino \
  -DarchetypeArtifactId=rhino-archetype \
  -DarchetypeVersion=2.2.1 \
  -DgroupId=com.acme \
  -DartifactId=my-foo-load-tests

For the groupId, you need to set your project’s groupId, that is specific to your project and organization e.g

1	com.yourcompany.testing

and the artifactId is some artifact id used to identify your project e.g

1	my-test-project

. After entering the mvn command above, the project will be created which can be imported in your IDE.

You may choose to create a Rhino project without using the Rhino archetype. In this case, you can add the Rhino core dependency into your POM file:

1
2
3
4
5
<dependency>
  <groupId>io.ryos.rhino</groupId>
  <artifactId>rhino-core</artifactId>
  <version>1.8.2</version>
</dependency>

rhino-hello-world located in the project’s root, might be a good starting point if you want to play around.

Writing your first Simulation with Scenarios

Rhino projects do consist of a main-method to run simulations and simulation entities which are annotated with Rhino annotations. An example application might look as follows:

1
2
3
4
5
6
7
8
9
10
11
import io.ryos.rhino.sdk.Simulation;

public class Rhino {

    private static final String PROPS = "classpath:///rhino.properties";
    private static final String SIM_NAME = "Server-Status Simulation";

    public static void main(String ... args) {
        Simulation.create(PROPS, SIM_NAME).start();
    }
}

1	Simulation

is the load testing controller instance which requires a configuration file in the classpath ( therefore

1	classpath://<absolute path to configuration file>

prefix is important) and the name of the simulation to be run. You can also put the properties file outside of the classpath e.g somewhere on your disk: “file:///home/user/rhino.properties”

The name of the simulation must match the name, set in Simulation annotation so that the Simulation controller can locate the Simulation entity:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
@Simulation(name = "Server-Status Simulation")
public class RhinoEntity {

  private static final String TARGET = "http://localhost:8089/api/status";
  private static final String X_REQUEST_ID = "X-Request-Id";
  
  private Client client = ClientBuilder.newClient();

  @Provider(factory = UUIDProvider.class)
  private UUIDProvider uuidProvider;

  @Scenario(name = "Health")
  public void performHealth(Measurement measurement) {
    var response = client
            .target(TARGET)
            .request()
            .header(X_REQUEST_ID, "Rhino-" + uuidProvider.take())
            .get();

    measurement.measure("Health API Call", String.valueOf(response.getStatus()));
  }
}

In the example above, we mark the simulation entity with

1	@Simulation

annotation with a unique name attribute. The simulation entity is a container for the scenario methods which are run by the Rhino runtime and annotated with @Scenario annotation. Each scenario method must have a name which is used in performance measurements and reporting, so the scenario method takes the name “Health” for healthcheck test. The scenario methods will take `Measurement instance to let load testing developers add measurement points. In the example, we measure the time elapsed between the method execution and http request completion. A scenario method might contain multiple measurement points.

Once you start the Rhino main method, the framework will start to call the performHealth- method repeatedly and after each call, it will measure the time elapsed.

Alternatively, you may choose the reactive style and implements a Load DSL:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
@Simulation(name = "Reactive Sleep Test")
@Runner(clazz = ReactiveHttpSimulationRunner.class)
public class ReactiveSleepTestSimulation {

  @Dsl(name = "Health")
  public LoadDsl performHealth() {
    return Start
        .dsl()
        .run(http("Health API Call")
            .header(c -> from(X_REQUEST_ID, "Rhino-" + UUID.randomUUID().toString()))
            .endpoint(TARGET)
            .get()
            .saveTo("result"));
  }
}

To enable the DSL mode, you need to add

1	ReactiveHttpSimulationRunner

to your Simulation. In this mode, the load testing developers describe how a load test is to be run instead of providing the implementation what to run.

The project is in its early development stage. Please feel free to join the community, use Rhino in your load test projects and create issues on Github. We appreciate your contributions on the project.

1
2
3
4
5
6
7
8
9
10
11
public class Cat {
    private AnimalSound sound;
   
    public Cat(AnimalSound animalSound) {
        this.sound = animalSound;
    }

    public void sing() {
        soundEffect(sound);
    }
}

In our game we have cats singing. How they sing is determined by AnimalSound which is the internal state of Cat we maintain, and defines its behaviour, respectively. Everthing looks so far good. We can now instantiate new Cat objects and let them sing as follows:

1
2
3
4
5
6
7
Cat cat1 = new Cat(AnimalSoundLib.MEOW);
cat1.sing(); // meooww

Cat cat2 = new Cat(AnimalSoundLib.MEOOO);
cat2.sing(); // meoooo

// more cats

Now, our game grows and we need new animals in our game’s universe. Let’s imagine that the farm is located right next to the woods and there are bigger cats like lions, leopards, etc. Since lions are also cats - “is a” relationship, we can easily create a subclass of Cat type for Lion, right?

1
2
3
4
5
6
7
8
9
public class Lion extends Cat {

    public Lion(AnimalSound animalSound) {
        super(animalSound);
    }

    public void hunt() {}
    // and other lion related methods.
}

Now, let’s create a new lion instance which roars:

1
2
Lion lion = new Lion(AnimalSoundLib.ROAR);
lion.sing(); // roarrr

But, the problem comes to light once you attempt to use the Lion instance in place of a Cat instance while relying on runtime polymorphism. Let’s have a Bar of Cats in which we only expect cute little meowing cats singing happily after work:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
public class CatBar {
    private List<Cat> catFriends = new ArrayList<>();

    public void enter(Cat cat) {
        catFriends.add(cat);
    }

    public void singTogether() {

        for (Cat cat: catFriends) {
            cat.sing();
        }
    }
}

At some level in our application, we rely on a cat service which gives us cat objects back and of which implementation is contributed from an external Cat services team. Since the cat service library is introduced as a dependency in our project, we just want to use the service to have some cats without knowing internal implementation details of it. It is also legitimate to have Lion instances out of catService, since lions are also cats!

1
2
3
4
5
6
7
Cat cat = catService.getCat(); // a real cat created which meows
catbar.enter(cat); 

Cat lion = catService.getCat(); // this time the service gives you a lion instance back.
catbar.enter(lion);

catbar.singTogether(); // party begins: meoww moewww ROOARRR meow

But, what happens if the service returns a Lion object, which is technically a Cat and a valid return type, and we pass it to our CatBar where only meowing cats are expected to enter? Now, we should expect to have a trouble since we changed the semantics of the Cat instance by overriding its internal representation from a subclass as we set the cat’s sound to a ROAR. Now, we will not be able to use the Cat instance above since it roars!

LSP tells us, we should be able to use the subclasses of class A, for instance, class B which extends class A in place of A, everywhere in our program without breaking the program’s behaviour.

The behavior of Cat instance has changed. On the other hand, runtime polymorphism allows to use subclasses of Cats, like Lion in our example, as Cats where we need which makes such an assignment valid. So, we violated the LSP which tells us, we should be able to use the subclasses of class A, for instance, class B which extends class A in place of A, everywhere in our program without breaking the program’s behaviour. In our CatBar, therefore, we don’t only hear meows but also roars out of our CatBar.