localsend / localsend/protocol

Include examples (and questions)

Open
#32 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Mermaid
Stars
572
Forks
42
PR merge metrics
No merged PRs in 30d

Description

I'm working on implementing the protocol as a KOReader plugin, and I had some difficulties understanding the protocol.

It would be really helpful if the repo included some examples of the entire protocol start to finish, either as text or pcap files, as it's a bit hard to piece together especially with https.

How is the protocol decided?

The protocol says that the possible protocols are http and https and that the discovery udp packet and response http post request include it, but doesn't describe how it's selected.
I interpreted it as the protocol in the request meaning set of supported protocols, with https meaning http or https, and the protocol in the response being the final decision from the set of supported protocols, so either participant can downgrade to http, is this correct? And responding with https after getting http is an error (errors also seems to be missing for this request)?

For my use case I rather avoid https if possible, I'm trying to use only lua with the already included libraries, so self-signing would be quite annoying and I don't have access a proper http server implementation.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No specific files or tests are named. Start with the protocol sections covering the discovery UDP packet, the response HTTP POST request, and protocol selection; compare them with the issue's questions about HTTP/HTTPS and errors. Done means adding complete end-to-end examples and documenting the protocol-selection behavior and relevant errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua
Domain
documentation, networking
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.