{"id":33143440,"url":"https://github.com/twitter/hbc","last_synced_at":"2025-11-16T03:01:33.785Z","repository":{"id":6816317,"uuid":"8064341","full_name":"twitter/hbc","owner":"twitter","description":"A Java HTTP client for consuming Twitter's realtime Streaming API","archived":true,"fork":false,"pushed_at":"2022-04-06T19:20:25.000Z","size":365,"stargazers_count":962,"open_issues_count":0,"forks_count":368,"subscribers_count":190,"default_branch":"master","last_synced_at":"2025-07-08T17:32:30.514Z","etag":null,"topics":["java","realtime","stream","tweets","twitter4j"],"latest_commit_sha":null,"homepage":"https://developer.twitter.com/en/docs/tweets/filter-realtime/overview","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/twitter.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-02-07T01:40:57.000Z","updated_at":"2025-07-04T09:40:57.000Z","dependencies_parsed_at":"2022-09-10T23:41:41.995Z","dependency_job_id":null,"html_url":"https://github.com/twitter/hbc","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/twitter/hbc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitter%2Fhbc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitter%2Fhbc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitter%2Fhbc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitter%2Fhbc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/twitter","download_url":"https://codeload.github.com/twitter/hbc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/twitter%2Fhbc/sbom","scorecard":{"id":904087,"data":{"date":"2025-08-18","repo":{"name":"github.com/twitter/hbc","commit":"d61647a23b4e3cbc88a6855a506c042692e686be"},"scorecard":{"version":"v5.2.1-41-g40576783","commit":"40576783fda6698350fcbbeaea760ff827433034"},"score":3.4,"checks":[{"name":"Code-Review","score":3,"reason":"Found 8/26 approved changesets -- score normalized to 3","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#packaging"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"project is archived","details":["Warn: Repository is archived."],"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#cii-best-practices"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#branch-protection"}},{"name":"Security-Policy","score":9,"reason":"security policy file detected","details":["Info: security policy file detected: github.com/twitter/.github/security.md:1","Info: Found linked content: github.com/twitter/.github/security.md:1","Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy","Info: Found text in security policy: github.com/twitter/.github/security.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#security-policy"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 13 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":4,"reason":"6 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GHSA-5mg8-w23w-74h3","Warn: Project is vulnerable to: GHSA-7g45-4rm6-3mm3","Warn: Project is vulnerable to: GHSA-mvr2-9pj6-7w5j","Warn: Project is vulnerable to: GHSA-7r82-7xv7-xcpj","Warn: Project is vulnerable to: GHSA-cfh5-3ghh-wfjx","Warn: Project is vulnerable to: GHSA-fmj5-wv96-r2ch"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/40576783fda6698350fcbbeaea760ff827433034/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-24T16:43:02.436Z","repository_id":6816317,"created_at":"2025-08-24T16:43:02.436Z","updated_at":"2025-08-24T16:43:02.436Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":284654194,"owners_count":27041729,"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","status":"online","status_checked_at":"2025-11-16T02:00:05.974Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["java","realtime","stream","tweets","twitter4j"],"created_at":"2025-11-15T13:00:25.546Z","updated_at":"2025-11-16T03:01:33.780Z","avatar_url":"https://github.com/twitter.png","language":"Java","readme":"# Hosebird Client (hbc) [![status: retired](https://opensource.twitter.dev/status/retired.svg)](https://opensource.twitter.dev/status/#retired)\n \nA Java HTTP client for consuming Twitter's standard [Streaming API](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview)\n\n!! As of March 2022, this code is [no longer maintained or supported](https://github.com/twitter/hbc/issues/210). \n\n!! Note that, as of August 16th, 2018, the [user streams and site streams features have been retired](https://twittercommunity.com/t/reminder-site-streams-user-streams-and-legacy-dm-endpoints-will-be-sunset-august-16th/109482), so code that attempts to connect to these endpoints will no longer work.\n\n## Features\n* GZip support\n* OAuth support\n* Partitioning support\n* Automatic reconnections with appropriate backfill counts\n* Access to raw bytes payload\n* Proper backoffs/retry schemes\n* Relevant statistics/events\n\n## Getting Started\n\nThe Hosebird client is broken down into two modules: hbc-core and hbc-twitter4j. The hbc-core module uses a message queue, which the consumer can poll for the raw String messages, while the hbc-twitter4j module uses the [twitter4j](http://twitter4j.org) listeners and data model on top of the message queue to provide a parsing layer.\n\nThe latest hbc artifacts are published to maven central. Bringing hbc into your project should be as simple as adding the following to your maven pom.xml file:\n\n```xml\n  \u003cdependencies\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003ecom.twitter\u003c/groupId\u003e\n      \u003cartifactId\u003ehbc-core\u003c/artifactId\u003e \u003c!-- or hbc-twitter4j --\u003e\n      \u003cversion\u003e2.2.0\u003c/version\u003e \u003c!-- or whatever the latest version is --\u003e\n    \u003c/dependency\u003e\n  \u003c/dependencies\u003e\n```\n\n### Quickstart\n\nDeclaring the connection information:\n```java\n/** Set up your blocking queues: Be sure to size these properly based on expected TPS of your stream */\nBlockingQueue\u003cString\u003e msgQueue = new LinkedBlockingQueue\u003cString\u003e(100000);\nBlockingQueue\u003cEvent\u003e eventQueue = new LinkedBlockingQueue\u003cEvent\u003e(1000);\n\n/** Declare the host you want to connect to, the endpoint, and authentication (basic auth or oauth) */\nHosts hosebirdHosts = new HttpHosts(Constants.STREAM_HOST);\nStatusesFilterEndpoint hosebirdEndpoint = new StatusesFilterEndpoint();\n// Optional: set up some followings and track terms\nList\u003cLong\u003e followings = Lists.newArrayList(1234L, 566788L);\nList\u003cString\u003e terms = Lists.newArrayList(\"twitter\", \"api\");\nhosebirdEndpoint.followings(followings);\nhosebirdEndpoint.trackTerms(terms);\n\n// These secrets should be read from a config file\nAuthentication hosebirdAuth = new OAuth1(\"consumerKey\", \"consumerSecret\", \"token\", \"secret\");\n```\n\nCreating a client:\n```java\nClientBuilder builder = new ClientBuilder()\n  .name(\"Hosebird-Client-01\")                              // optional: mainly for the logs\n  .hosts(hosebirdHosts)\n  .authentication(hosebirdAuth)\n  .endpoint(hosebirdEndpoint)\n  .processor(new StringDelimitedProcessor(msgQueue))\n  .eventMessageQueue(eventQueue);                          // optional: use this if you want to process client events\n\nClient hosebirdClient = builder.build();\n// Attempts to establish a connection.\nhosebirdClient.connect();\n```\n\nNow, msgQueue and eventQueue will now start being filled with messages/events. Read from these queues however you like.\n```java\n// on a different thread, or multiple different threads....\nwhile (!hosebirdClient.isDone()) {\n  String msg = msgQueue.take();\n  something(msg);\n  profit();\n}\n```\n\nYou can close a connection with\n\n```java\nhosebirdClient.stop();\n```\n\n### Quick Start Example\n\nTo run the sample stream example:\n\n```\nmvn install \u0026\u0026 mvn exec:java -pl hbc-example -Dconsumer.key=XYZ -Dconsumer.secret=SECRET -Daccess.token=ABC -Daccess.token.secret=ABCSECRET\n```\n\nYou can find these values on http://developer.twitter.com and navigating to one of your applications then to the Keys and Tokens tab.\nThe Consumer API key and secrets values on that page correspond to hbc's `-Dconsumer.*` properties.\n\nAlternatively you can set those properties in hbc-examples/pom.xml\n\n## The Details\n\n### Authentication:\n\nDeclaring OAuth1 credentials in the client:\n\n```java\nnew OAuth1(\"consumerKey\", \"consumerSecret\", \"token\", \"tokenSecret\")\n```\n\nBe sure not to pass your tokens as strings directly into the initializers. They should be read from a configuration file that isn't checked in with your code or something similar. Safety first.\n\n### Specifying an endpoint\n\nDeclare a StreamingEndpoint to connect to. These classes reside in the package com.twitter.hbc.core.endpoint, and correspond to all of our endpoints. By default, the HTTP parameter \"delimited=length\" is set for all of our StreamingEndpoints for compatibility with our processor (next section). If you are using our StringDelimitedProcessor this parameter must be set. For a list of available public endpoints and the http parameters we support, see [Twitter's Streaming API docs](https://developer.twitter.com/en/docs/tweets/filter-realtime/overview).\n\n#### Filter streams:\n\n```java\nStatusesFilterEndpoint endpoint = new StatusesFilterEndpoint();\n// Optional: set up some followings and track terms\nList\u003cLong\u003e followings = Lists.newArrayList(1234L, 566788L);\nList\u003cString\u003e terms = Lists.newArrayList(\"twitter\", \"api\");\nendpoint.followings(followings);\nendpoint.trackTerms(terms);\n```\n\n#### Setting up a Processor:\n\nThe hosebird client uses the notion of a \"processor\" which processes the stream and put individual messages into the provided BlockingQueue. We provide a StringDelimitedProcessor class which should be used in conjunction with the StreamingEndpoints provided. The processor takes as its parameter a BlockingQueue, which the client will put String messages into as it streams them.\n\nSetting up a StringDelimitedProcessor is as easy as:\n\n```java\nnew StringDelimitedProcessor(msgQueue);\n```\n\n### The hbc-twitter4j module\n\nThe hbc-twitter4j module uses the twitter4j listeners and models. To use it, create a normal Client object like before using the ClientBuilder, then depending on which type of stream you are reading from, create an appropriate Twitter4jClient. The Twitter4jClient wraps around the Client it is passed, and calls the callback methods in the twitter4j listeners whenever it retrieves a message from the message queue. The actual work of polling from the message queue, parsing, and executing the callback method is done by forking threads from an executor service that the client is passed.\n\nIf connecting to a status stream (filter, firehose, sample), use Twitter4jStatusClient:\n\n```java\n// client is our Client object\n// msgQueue is our BlockingQueue\u003cString\u003e of messages that the handlers will receive from\n// listeners is a List\u003cStatusListener\u003e of the t4j StatusListeners\n// executorService\nTwitter4jClient t4jClient = new Twitter4jStatusClient(client, msgQueue, listeners, executorService);\nt4jClient.connect();\n\n// Call this once for every thread you want to spin off for processing the raw messages.\n// This should be called at least once.\nt4jClient.process(); // required to start processing the messages\nt4jClient.process(); // optional: another Runnable is submitted to the executorService to process the msgQueue\nt4jClient.process(); // optional\n```\n\n#### Using Handlers, a Twitter4j listener add-on\n\nAll Twitter4jClients support Handlers, which extend their respective Twitter4j listeners: StatusStreamHandler extends StatusesListener. These handlers have extra callback menthods that may be helpful for parsing messages that the Twitter4j listeners do not yet support\n\n## Building / Testing\n\nTo build locally (you must use java 1.7 for compiling, though we produce 1.6 compatible classes):\n\n```\nmvn compile\n```\nTo run tests:\n\n```\nmvn test\n```\n\n## Authors:\n* Steven Liu\n* Kevin Oliver\n\n## License\nCopyright 2013 Twitter, Inc.\n\nLicensed under the Apache License, Version 2.0: http://www.apache.org/licenses/LICENSE-2.0\n\n","funding_links":[],"categories":["III. Network and Integration","网络编程"],"sub_categories":["10. Integratin with API"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwitter%2Fhbc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftwitter%2Fhbc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftwitter%2Fhbc/lists"}