{"id":18753022,"url":"https://github.com/spotify/folsom","last_synced_at":"2025-05-15T17:05:56.100Z","repository":{"id":27287973,"uuid":"30761550","full_name":"spotify/folsom","owner":"spotify","description":"An asynchronous memcache client for Java","archived":false,"fork":false,"pushed_at":"2024-12-17T13:42:54.000Z","size":1176,"stargazers_count":147,"open_issues_count":17,"forks_count":68,"subscribers_count":94,"default_branch":"master","last_synced_at":"2025-04-07T22:08:48.465Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/spotify.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-02-13T15:12:37.000Z","updated_at":"2025-03-18T17:31:02.000Z","dependencies_parsed_at":"2023-11-13T13:46:57.597Z","dependency_job_id":"b699542c-f118-4141-bf04-2b189b0a8748","html_url":"https://github.com/spotify/folsom","commit_stats":{"total_commits":475,"total_committers":37,"mean_commits":"12.837837837837839","dds":"0.47578947368421054","last_synced_commit":"13fa3b3ad18aee04b2a656b1109e77988b8b56f7"},"previous_names":[],"tags_count":56,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Ffolsom","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Ffolsom/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Ffolsom/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/spotify%2Ffolsom/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/spotify","download_url":"https://codeload.github.com/spotify/folsom/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384988,"owners_count":22062422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T17:23:51.399Z","updated_at":"2025-05-15T17:05:51.091Z","avatar_url":"https://github.com/spotify.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Folsom\n\nFolsom is an attempt at a small and stable memcache client. Folsom is fully\nasynchronous, based on Netty and uses Java 8's CompletionStage through-out the\nAPI.\n\n### Build status\n\n![Build status](https://github.com/spotify/folsom/actions/workflows/maven.yml/badge.svg)\n\n### Maven central\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.spotify/folsom/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.spotify/folsom)\n\n\n### Build dependencies\n\n* Java 8 or higher\n* Maven\n* Docker - to run integration tests.\n\n### Runtime dependencies\n\n* Netty 4\n* Google Guava\n* Yammer metrics (optional)\n* OpenCensus (optional)\n\n### Usage\n\nFolsom is meant to be used as a library embedded in other software.\n\nTo import it with maven, use this:\n\n    \u003c!-- In dependencyManagement section --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom-bom\u003c/artifactId\u003e\n      \u003cversion\u003e1.14.0\u003c/version\u003e\n      \u003ctype\u003epom\u003c/type\u003e\n      \u003cscope\u003eimport\u003c/scope\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- In dependencies section --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- optional if you want to expose folsom metrics with spotify-semantic-metrics --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom-semantic-metrics\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- optional if you want to expose folsom metrics with yammer --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom-yammer-metrics\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- optional if you want to expose folsom tracing with OpenCensus --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom-opencensus\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n\n    \u003c!-- optional if you want to use AWS ElastiCache auto-discovery --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom-elasticache\u003c/artifactId\u003e\n    \u003c/dependency\u003e\n\nIf you want to use one of the metrics or tracing libraries, make sure you use the same version as\nthe main artifact.\n\nWe are using [semantic versioning](http://semver.org)\n\nThe main entry point to the folsom API is the MemcacheClientBuilder class. It has\nchainable setter methods to configure various aspects of the client. The methods connectBinary()\nand connectAscii() constructs MemcacheClient instances utilising the [binary protocol] and\n[ascii protocol] respectively. For details on their differences see **Protocol** below.\n\nAll calls to the folsom API that interacts with a memcache server is asynchronous and the\nresult is typically accessible from CompletionStage instances. An exception to this rule\nare the methods that connects clients to their remote endpoints,\nMemcacheClientBuilder.connectBinary() and MemcacheClientBuilder.connectAscii() which will\nreturn a MemcacheClient immediately while asynchronously attempting to connect to the configured\nremote endpoint(s).\n\nAs code using the folsom API should be written so that it handles failing intermittently with\nMemcacheClosedException anyway, waiting for the initial connect to complete is not something\nfolsom concerns itself with. For single server connections, ConnectFuture provides functionality\nto wait for the initial connection to succeed, as can be seen in the example below.\n\n```Java\nfinal MemcacheClient\u003cString\u003e client = MemcacheClientBuilder.newStringClient()\n    .withAddress(hostname)\n    .connectAscii();\n// make it wait until the client has connected to the server\nConnectFuture.connectFuture(client).toCompletableFuture().get();\n\nclient.set(\"key\", \"value\", 10000).toCompletableFuture().get();\nclient.get(\"key\").toCompletableFuture().get();\n\nclient.shutdown();\n```\n\nClients are single use, after `shutdown` has been invoked the client can no\nlonger be used.\n\n#### To work with generic `Serializable` types\n\nOne can simply use `MemcacheClientBuilder.\u003cT\u003enewSerializableObjectClient()`\nmethod to create a client that works for a specific Java type that implements `Serializable`.\n\n```java\npublic record Student(String name, int age) implements Serializable { }\n\npublic static void main(String[] args) throws Exception {\n  MemcacheClient\u003cStudent\u003e client =\n      MemcacheClientBuilder.\u003cStudent\u003enewSerializableObjectClient()\n      .withAddress(\"localhost\")\n      .connectAscii();\n  // make it wait until the client has connected to the server\n  ConnectFuture.connectFuture(client).toCompletableFuture().get();\n\n  client.set(\"s1\", new Student(\"Elon\", 28), 10000).toCompletableFuture().get();\n  Student value = client.get(\"s1\").toCompletableFuture().get();\n}\n```\n\n### Java 7 usage\n\nIf you are still on Java 7, you can depend on the older version:\n\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.spotify\u003c/groupId\u003e\n      \u003cartifactId\u003efolsom\u003c/artifactId\u003e\n      \u003cversion\u003e0.8.1\u003c/version\u003e\n    \u003c/dependency\u003e\n\n### Design goals\n\n* Robustness - If you request something, the future you get back should always complete at some point.\n* Error detection - If something goes wrong (the memcache server is behaving incorrectly or some internal bug occurs),\n  we try to detect it and drop the connection to prevent further problems.\n* Simplicity - The code base is intended to be small and well abstracted.\n  We prefer simple solutions that solve the major usecases and avoid implementing optimizations\n  that would give small returns.\n* Fail-fast - If something happens (the memcached service is slow or gets disconnected) we try to fail as fast as possible.\n  How to handle the error is up to you, and you probably want to know about the error as soon as possible.\n* Modularity - The complex client code is isolated in a single class, and all the extra functionality are in composable modules:\n  (ketama, reconnecting, retry, roundrobin)\n* Efficiency - We want to support a high traffic throughput without using too much CPU or memory resources.\n* Asynchronous - We fully support the idea of writing asynchronous code instead of blocking threads, and this is\n  achieved through Java 8 futures.\n* Low amount of synchronization - Code that uses a lot of synchronization primitives is more likely to have\n  race condition bugs and deadlocks. We try to isolate that as much as possible to minimize the risk,\n  and most of the code base doesn't have to care.\n\n### Best practices\n\nDo not use `withConnectionTimeoutMillis()` or the deprecated `withRequestTimeoutMillis()` to set timeouts per request.\nThis is intended to detect broken TCP connections to close it and recreate it. Once this happens, all open\nrequests will be completed with a failure and Folsom will try to recreate the connection. If this timeout is set too low,\nthis will create connection flapping which will result in an increase of failed requests and/or increased\nrequest latencies.\n\nA better way of setting timeouts on individual requests (in Java 9+) is something like this:\n\n```java\nCompletableFuture\u003cT\u003e future = client.get(...)\n  .toCompletableFuture()\n  .orTimeout(...)\n  .whenCompleteAsync((v, e) -\u003e {}, executor);\n```\n\nNote that in case of timeouts, the futures from `orTimeout` would all be completed on a singleton thread, which may cause contention.\nTo avoid problems with that, we add `whenCompleteAsync` to ensure that\nthe work is moved to an executor that has sufficient threads.\n\n### Protocol\n\nFolsom implements both the [binary protocol] and [ascii protocol].\nThey share a common interface but also extend it with their own specializations.\n\nWhich protocol to use depends on your use case. With a regular memcached backend,\nthe ascii protocol is much more efficient. The binary protocol is a bit chattier\nbut also makes error detection easier.\n\n```Java\ninterface MemcacheClient\u003cT\u003e {}\ninterface AsciiMemcacheClient\u003cT\u003e extends MemcacheClient\u003cT\u003e {}\ninterface BinaryMemcacheClient\u003cT\u003e extends MemcacheClient\u003cT\u003e {}\n```\n\n### Changelog\nSee [changelog](CHANGELOG.md).\n\n### Features\n\n#### Ketama\n\nFolsom support Ketama for sharing across a set of memcache servers. Note that\nthe caching algorithm (currently) doesn't attempt to provide compatibility with\nother memcache clients, and thus when switching client implementation you will\nget a period of low cache hit ratio.\n\n#### Micrometer metrics\n\nYou can optionally choose to track performance using\n[Micrometer metrics](https://micrometer.io/).\nYou will need to include the `folsom-micrometer-metrics` dependency and initialize\nusing MemcacheClientBuilder. (Optionally add additional tags):\n\n```\nbuilder.withMetrics(new MicrometerMetrics(metricsRegistry));\n```\n\n#### Yammer metrics\n\nYou can optionally choose to track performance using\n[Yammer metrics](https://metrics.dropwizard.io/4.0.0/).\nYou will need to include the `folsom-yammer-metrics` dependency and initialize\nusing MemcacheClientBuilder:\n\n```\nbuilder.withMetrics(new YammerMetrics(metricsRegistry));\n```\n\n#### OpenTelemetry metrics\n\nYou can optionally choose to track performance using\n[OpenTelemetry metrics](https://opentelemetry.io/).\nYou will need to include the `folsom-opentelemetry-metrics` dependency and initialize\nusing MemcacheClientBuilder:\n\n```\nbuilder.withMetrics(new OpenTelemetryMetrics(metricsRegistry));\n```\n\n#### OpenCensus tracing\n\nYou can optionally use [OpenCensus](https://opencensus.io/) to trace Folsom operations.\nYou will need to include the `folsom-opencensus` dependency and initialize tracing\nusing MemcacheClientBuilder:\n\n```\nbuilder.withTracer(OpenCensus.tracer());\n```\n\n#### Cluster auto-discovery\n\nNodes in a memcache clusters can be auto-discovered. Folsom supports discovery through \nDNS SRV records using the `com.spotify.folsom.SrvResolver` or AWS ElastiCache using the\n`com.spotify.folsom.elasticache.ElastiCacheResolver`.\n\nSrvResolver:\n```\nbuilder.withResolver(SrvResolver.newBuilder(\"foo._tcp.example.org\").build());\n```\n\nElastiCacheResolver:\n```\nbuilder.withResolver(ElastiCacheResolver.newBuilder(\"cluster-configuration-endpoint-hostname\").build());\n```\n\n### Building\n\n```\nmvn package\n```\n\n## Code of conduct\nThis project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code.\n\n### Authors\n\nFolsom was initially built at [Spotify](https://github.com/spotify) by\n[Kristofer Karlsson](https://github.com/krka), [Niklas Gustavsson](https://github.com/protocol7) and\n[Daniel Norberg](https://github.com/danielnorberg).\nMany thanks also go out to [Noa Resare](https://github.com/noaresare).\n\n[binary protocol]: https://github.com/memcached/memcached/wiki/BinaryProtocolRevamped\n[ascii protocol]: https://github.com/memcached/memcached/blob/master/doc/protocol.txt\n[code-of-conduct]: https://github.com/spotify/code-of-conduct/blob/master/code-of-conduct.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotify%2Ffolsom","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fspotify%2Ffolsom","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fspotify%2Ffolsom/lists"}