docs: add block api #68
Conversation
WalkthroughThe changes introduce new methods for blocking and unblocking URLs in the Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Justfile
participant API
User->>Justfile: Call block-url(url)
Justfile->>API: POST /api/v0/admin/block-url?url={url}&token={HATSU_ACCESS_TOKEN}
API-->>Justfile: Response (success/failure)
User->>Justfile: Call unblock-url(url)
Justfile->>API: POST /api/v0/admin/unblock-url?url={url}&token={HATSU_ACCESS_TOKEN}
API-->>Justfile: Response (success/failure)
Poem
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Outside diff range and nitpick comments (6)
docs/src/SUMMARY.md (1)
28-28: LGTM! Consider a minor clarification.The new entry "Block Instances or Actors" is correctly placed and formatted. It fits well within the "for Admins" section and follows the established pattern for documentation links.
For improved clarity, consider slightly expanding the title to "Block Remote Instances or Actors". This could help administrators immediately understand that this refers to external entities, not local ones.
-- [Block Instances or Actors](./admins/block-instances-or-actors.md) ++ [Block Remote Instances or Actors](./admins/block-instances-or-actors.md)docs/src/admins/block-instances-or-actors.md (5)
1-3: Minor grammatical improvement suggestedThe sentence structure in the note about setting
HATSU_ACCESS_TOKENcan be improved for better readability.Consider revising the sentence as follows:
-> Ensure you set `HATSU_ACCESS_TOKEN` correctly in the [previous section](./environments.md#hatsu_access_token-optional) first, otherwise you will not be able to use the Hatsu Admin API. +> Ensure you set `HATSU_ACCESS_TOKEN` correctly in the [previous section](./environments.md#hatsu_access_token-optional) first. Otherwise, you will not be able to use the Hatsu Admin API.This change separates the two clauses into distinct sentences, improving clarity.
🧰 Tools
🪛 LanguageTool
[typographical] ~3-~3: The word “otherwise” is an adverb that can’t be used like a conjunction, and therefore needs to be separated from the sentence.
Context: ...onments.md#hatsu_access_token-optional) first, otherwise you will not be able to use the Hatsu A...(THUS_SENTENCE)
7-8: Enhance explanation and improve grammarThe explanation about blocking URLs could be more detailed, and there's a minor grammar issue.
Consider revising as follows:
-Block URL. if path is `/`, it is recognized as an instance. +Block a URL using this API. If the path is `/`, it is recognized as an instance. Otherwise, it is treated as an actor.This change provides more context and fixes the capitalization issue.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~7-~7: Possible missing article found.
Context: ...Admin API. ## Block URL Block URL. if path is/, it is recognized as an instance...(AI_HYDRA_LEO_MISSING_A)
9-9: Improve sentence structureThe sentence structure can be improved for better readability.
Consider revising as follows:
-Each time an activity is received an origin match is performed on blocked instances and an exact match is performed on blocked actors. +Each time an activity is received, an origin match is performed on blocked instances, and an exact match is performed on blocked actors.This change adds necessary commas to improve readability.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~9-~9: Possible missing comma found.
Context: ... an instance. Each time an activity is received an origin match is performed on blocked...(AI_HYDRA_LEO_MISSING_COMMA)
11-13: Improve curl command readabilityThe curl command example could be formatted for better readability.
Consider restructuring the command as follows:
BLOCK_URL="https://example.com" HATSU_API_URL="http://localhost:$(echo $HATSU_LISTEN_PORT)" curl -X POST "${HATSU_API_URL}/api/v0/admin/block-url" \ -d "url=${BLOCK_URL}" \ -d "token=${HATSU_ACCESS_TOKEN}"This format:
- Separates the URL construction for clarity.
- Uses
-dfor data parameters, which is more common and readable.- Splits the command across multiple lines for better readability.
15-15: Correct grammatical error in section titleThere's a minor grammatical error in the section title.
Please revise the title as follows:
-### Get the Actors URL for a Fediverse user +### Get the Actor's URL for a Fediverse userThis change adds the missing apostrophe to make "Actor's" possessive.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~15-~15: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ... $HATSU_ACCESS_TOKEN)" ``` ### Get the Actors URL for a Fediverse user In Fediverse,...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (4)
- Justfile (1 hunks)
- docs/src/SUMMARY.md (1 hunks)
- docs/src/admins/block-instances-or-actors.md (1 hunks)
- docs/src/admins/create-account.md (1 hunks)
🧰 Additional context used
🪛 LanguageTool
docs/src/admins/block-instances-or-actors.md
[typographical] ~3-~3: The word “otherwise” is an adverb that can’t be used like a conjunction, and therefore needs to be separated from the sentence.
Context: ...onments.md#hatsu_access_token-optional) first, otherwise you will not be able to use the Hatsu A...(THUS_SENTENCE)
[uncategorized] ~7-~7: Possible missing article found.
Context: ...Admin API. ## Block URL Block URL. if path is/, it is recognized as an instance...(AI_HYDRA_LEO_MISSING_A)
[uncategorized] ~9-~9: Possible missing comma found.
Context: ... an instance. Each time an activity is received an origin match is performed on blocked...(AI_HYDRA_LEO_MISSING_COMMA)
[uncategorized] ~15-~15: It seems likely that a singular genitive (’s) apostrophe is missing.
Context: ... $HATSU_ACCESS_TOKEN)" ``` ### Get the Actors URL for a Fediverse user In Fediverse,...(AI_HYDRA_LEO_APOSTROPHE_S_XS)
docs/src/admins/create-account.md
[typographical] ~3-~3: The word “otherwise” is an adverb that can’t be used like a conjunction, and therefore needs to be separated from the sentence.
Context: ...onments.md#hatsu_access_token-optional) first, otherwise you will not be able to use the Hatsu A...(THUS_SENTENCE)
🔇 Additional comments (3)
Justfile (3)
83-85: 🛠️ Refactor suggestionRefactor
unblock-urlmethod and reduce duplication.The
unblock-urlmethod has the same structure and potential improvements as theblock-urlmethod. To reduce duplication and improve maintainability, consider refactoring both methods to use a common helper function.Here's a suggested refactor:
-block-url url: - curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/block-url?url={{url}}&token=${HATSU_ACCESS_TOKEN}" - -# /api/v0/admin/unblock-url -unblock-url url: - curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/unblock-url?url={{url}}&token=${HATSU_ACCESS_TOKEN}" +# Helper function for URL operations +_url_operation operation url: + #!/bin/sh + response=$(curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/{{operation}}-url" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${HATSU_ACCESS_TOKEN}" \ + -d "{\"url\": \"{{url}}\"}" \ + -s -w "\n%{http_code}") + body=$(echo "$response" | sed -n '1p') + code=$(echo "$response" | sed -n '2p') + if [ "$code" = "200" ]; then + echo "URL {{operation}} successful" + else + echo "Error: $body" + fi + +# /api/v0/admin/block-url +block-url url: + just _url_operation "block" "{{url}}" + +# /api/v0/admin/unblock-url +unblock-url url: + just _url_operation "unblock" "{{url}}"This refactored version:
- Creates a helper function
_url_operationthat handles the common logic.- Uses this helper function in both
block-urlandunblock-urlmethods.- Implements the improvements suggested in the previous comment (body parameters, authorization header, error handling).
- Reduces code duplication and improves maintainability.
Let's check if there are any other similar API calls in the Justfile that could benefit from this pattern:
#!/bin/bash # Search for other API calls in the Justfile rg 'curl.*POST.*api/v0/admin' Justfile
79-85: 🛠️ Refactor suggestionConsider standardizing API call patterns across the Justfile.
The new
block-urlandunblock-urlmethods are good additions that align with the existing structure of the Justfile. However, there's an opportunity to improve consistency across all API-related commands in the file.
Review all API-related commands in the Justfile (e.g.,
account,block-url,unblock-url) and consider applying a consistent pattern for making API calls. This could involve:
- Using a common helper function for API calls.
- Consistent error handling and response processing.
- Uniform use of headers (e.g., Content-Type, Authorization).
Consider adding a comment block at the top of the file explaining the common patterns and conventions used for API calls in this Justfile. This will help future contributors maintain consistency.
If not already present, consider adding a
.env.examplefile to the project root, listing all the environment variables used in this Justfile (likeHATSU_LISTEN_PORTandHATSU_ACCESS_TOKEN). This will help new developers set up their environment correctly.Let's check for all API-related commands in the Justfile:
This will help us identify all places where we might want to apply consistent patterns.
✅ Verification successful
API call patterns are consistent across the Justfile.
Verified that all API-related commands (
account,block-url,unblock-url) follow a consistent pattern in their curl usage and environment variable configurations. No further standardization is necessary at this time.🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash # Search for all API-related commands in the Justfile rg 'curl.*api/v0' JustfileLength of output: 383
79-81: 🛠️ Refactor suggestionConsider improving the
block-urlmethod implementation.The method successfully implements the block URL functionality, which aligns with the PR objective. However, there are a few points to consider:
- For POST requests, it's generally better to send data in the request body rather than as query parameters. This is especially important for potentially long or complex URLs.
- The method doesn't handle errors or process the response, which could make debugging difficult.
Consider refactoring the method like this:
block-url url: - curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/block-url?url={{url}}&token=${HATSU_ACCESS_TOKEN}" + curl -X POST "http://localhost:${HATSU_LISTEN_PORT}/api/v0/admin/block-url" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer ${HATSU_ACCESS_TOKEN}" \ + -d "{\"url\": \"{{url}}\"}" \ + -s -w "\n%{http_code}" \ + | awk 'NR==1{body=$0} NR==2{code=$0} END{if(code==200) {print "URL blocked successfully"} else {print "Error: " body}}'This refactored version:
- Sends the URL in the request body.
- Uses a proper Authorization header for the token.
- Processes the response to provide meaningful feedback.
To ensure consistency across the codebase, let's check if there are other instances of API calls that might benefit from similar improvements:
Summary by CodeRabbit
New Features
Documentation