Gorilla

A Distributed Lock Service, Set up in Minutes.

Gorilla is a distributed lock service that allows multiple processes or nodes to coordinate and synchronize access to a shared resource or data.

Getting Started

To install dependencies.

$ make deps

To create and migrate your database.

$ make migrate

To start the application.

$ cp .env.example .env.local
$ export $(cat .env | xargs)

$ make run

Now you can visit localhost:4000 from your browser.

To run test cases:

$ make ci

To list all commands:

$ make

To run postgresql with docker

$ docker run -itd \
    -e POSTGRES_USER=gorilla \
    -e POSTGRES_PASSWORD=gorilla \
    -e POSTGRES_DB=gorilla_dev \
    -p 5432:5432 \
    --name postgresql \
    postgres:15.2

$ podman run -itd \
    -e POSTGRES_USER=brangus \
    -e POSTGRES_PASSWORD=brangus \
    -e POSTGRES_DB=brangus_dev \
    -p 5432:5432 \
    --name postgresql \
    postgres:15.2

# https://github.com/dbcli/pgcli
$ psql -h 127.0.0.1 -U brangus -d brangus_dev -W

Service Endpoints

• Acquire Lock: Acquire a lock for a specific resource.

Endpoint:
    POST /api/v1/locks/{resource}

Request Body:
    {
        "owner": "<unique identifier for the requester>",
        "timeout": "<maximum time (in seconds) the lock can be held>",
        "metadata": "<any additional metadata for the lock>"
    }

Response:
    HTTP/1.1 200 OK
    {
        "id": <The lock ID>,
        "owner": "<The lock owner>",
        "resource": "<The lock resource name>",
        "token": "<A new unique token for the extended lock>",
        "timeout": <Actual time (in seconds) the lock can be held>,
        "metadata": ["list", "of", "metadata"],
        "createdAt": "2023-03-14T18:35:04",
        "updatedAt": "2023-03-14T18:35:04",
        "expireAt": "2023-03-14T19:35:04"
    }

Possible errors:
    HTTP/1.1 409 Conflict: The lock is already held by another owner.
    HTTP/1.1 400 Bad Request: The request is invalid or missing required parameters.

• Release Lock: Release a lock for a specific resource.

Endpoint:
    DELETE /api/v1/locks/{resource}/{token}

Response:
    HTTP/1.1 204 No Content

Possible errors:
    HTTP/1.1 404 Not Found: The token is not associated with any lock for the resource.

• Check Lock Status: Get the status of a lock for a specific resource.

Endpoint:
    GET /api/v1/locks/{resource}/{token}

Response:
    HTTP/1.1 200 OK
    {
        "id": <The lock ID>,
        "owner": "<The lock owner>",
        "resource": "<The lock resource name>",
        "token": "<A new unique token for the extended lock>",
        "timeout": <Actual time (in seconds) the lock can be held>,
        "metadata": ["list", "of", "metadata"],
        "createdAt": "2023-03-14T18:35:04",
        "updatedAt": "2023-03-14T18:35:04",
        "expireAt": "2023-03-14T19:35:04"
    }

Possible errors:
    HTTP/1.1 404 Not Found: The token is not associated with any lock for the resource.

• Extend Lock Time: Extend the time a lock is held for a specific resource.

Endpoint:
    PUT /api/v1/locks/{resource}/{token}

Request Body:
    {
        "timeout": <maximum time (in seconds) the lock can be held>
    }

Response:
    HTTP/1.1 200 OK
    {
        "id": <The lock ID>,
        "owner": "<The lock owner>",
        "resource": "<The lock resource name>",
        "token": "<A new unique token for the extended lock>",
        "timeout": <Actual time (in seconds) the lock can be held>,
        "metadata": ["list", "of", "metadata"],
        "createdAt": "2023-03-14T18:35:04",
        "updatedAt": "2023-03-14T18:35:04",
        "expireAt": "2023-03-14T19:35:04"
    }

Possible errors:
    HTTP/1.1 404 Not Found: The token is not associated with any lock for the resource.
    HTTP/1.1 409 Conflict: The lock is already held by another owner or the extended timeout is less than the remaining time of the lock.

Versioning

For transparency into our release cycle and in striving to maintain backward compatibility, Gorilla is maintained under the Semantic Versioning guidelines and release process is predictable and business-friendly.

See the Releases section of our GitHub project for changelogs for each release version of Gorilla. It contains summaries of the most noteworthy changes made in each release. Also see the Milestones section for the future roadmap.

Bug tracker

If you have any suggestions, bug reports, or annoyances please report them to our issue tracker at https://github.com/clevenio/gorilla/issues

Security Issues

If you discover a security vulnerability within Gorilla, please send an email to hello@clivern.com

Contributing

We are an open source, community-driven project so please feel free to join us. see the contributing guidelines for more details.

License

© 2023, Clivern. Released under MIT License.

Gorilla is authored and maintained by @clivern.