tjp
/
gus
Archived
2
0
Fork 0
Code Issues Pull Requests Projects Releases 3 Activity

README updates
continuous-integration/drone/push Build is passing Details

This commit is contained in:
tjpcc 2023-01-28 15:22:38 -07:00
parent 66a1b1f39a
commit 84d8e515be
2 changed files with 43 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

34
README.gmi
View File

@ -2,7 +2,7 @@
Gus is the toolkit for working with the small web in Go.
Think of it as a net/http for small web protocols. You still have to write your server, but you can focus on the logic you want to implement knowing the protocol is already dealt with. It's been said of gemini that you can write your server in a day. Now you can write it in under an hour.
Think of it as a net/http for small web protocols. You still have to write your server, but you can focus on the logic you want to implement knowing the protocol is already dealt with. It's been said of gemini that you can write your server in a day. Now you can write it in well under an hour.
## The "gus" package
@ -15,27 +15,35 @@ Gus is carefully structured as composable building blocks. The top-level package
* a "Middleware" abstraction
* some useful Handler wrappers: filtering, falling through a list of handlers
## gus/gemini
## Protocols
Gus is determined to be structured as composable building blocks, and the gemini package mainly just defines the structure that holds the blocks together.
The packages gus/gemini and gus/gopher provide concrete implementations of gus abstractions specific to those protocols.
* I/O (parsing, formatting) request and responses
* constructors for the various kinds of protocol responses
* helpers for building a protocol-suitable TLS config
* Client implementations
* Servers which can run your Handlers.
The gemini package provides some gemini-specific concrete implementations.
* I/O (parsing, formatting) request and responses for the gemini protocol
* constructors for the various kinds of gemini protocol responses
* a helper for building a gemini-suitable TLS config
* a Client implementation
* a Server which can run your Handlers.
The primary text formats for those protocols have higher-level support provided in sub-packages:
* gus/gemini/gemtext supports parsing gemtext and getting direct programmatic access to its AST. Deeper sub-packages provide converters to other formats (markdown and HTML) with overridable templates.
* gus/gopher/gophermap similarly parses the gophermap format and provides access to its AST.
## gus/gemini/gemtext
## Logging
The gemtext package provides a parser and converters for gemtext documents. It exposes an AST representation for parsed gemtext, and functions to write that AST out as other formats (currently markdown and HTML are supported, but more are planned).
Gus borrows the logging interface from go-kit.
=> https://pkg.go.dev/github.com/go-kit/log#Logger The logger interface from go-kit/log.
The gus/logging package provides everything you need to get a good basic start to producing helpful logs.
* A request-logging middleware with common diagnostics (time, duration, url, status codes, response body lengths)
* A simple constructor of useful default loggers at various levels. They output colorful logfmt lines to stdout.
## gus/contrib/*
This is where useful building blocks themselves start to come in. Sub-packages of contrib include Handler and Middleware implementations which accomplish the things your servers actually need to do.
The sub-packages include:
* log contains a simple request-logging middleware
* fs has handlers that make file servers possible: serve files, build directory listings, etc
* cgi includes handlers which can execute CGI programs
* sharedhost which provides means of handling /~username URLs
@ -62,7 +70,7 @@ There's lots still to do, and contributions are very welcome!
=> https://tildegit.org/tjp/gus submit an issue or pull request on the tildegit repository,
=> mailto:tjp@ctrl-c.club send me an email directly,
or poke me on IRC: I'm @tjp on irc.tilde.chat, and you'll find me in #gemini
or poke me on IRC: I'm @tjp on irc.tilde.chat where you'll find me in #gemini
------------------------

35
README.md
View File

@ -3,7 +3,7 @@
Gus is the toolkit for working with the small web in Go.
Think of it as a net/http for small web protocols. You still have to write your server, but you can focus on the logic you want to implement knowing the protocol is already dealt with. It's been said of gemini that you can write your server in a day. Now you can write it in under an hour.
Think of it as a net/http for small web protocols. You still have to write your server, but you can focus on the logic you want to implement knowing the protocol is already dealt with. It's been said of gemini that you can write your server in a day. Now you can write it in well under an hour.
## The "gus" package
@ -16,21 +16,31 @@ Gus is carefully structured as composable building blocks. The top-level package
* a "Middleware" abstraction
* some useful Handler wrappers: filtering, falling through a list of handlers
## gus/gemini
## Protocols
Gus is determined to be structured as composable building blocks, and the gemini package mainly just defines the structure that holds the blocks together.
The packages gus/gemini and gus/gopher provide concrete implementations of gus abstractions specific to those protocols.
The gemini package provides some gemini-specific concrete implementations.
* I/O (parsing, formatting) request and responses
* constructors for the various kinds of protocol responses
* helpers for building a protocol-suitable TLS config
* Client implementations
* Servers which can run your Handlers.
* I/O (parsing, formatting) request and responses for the gemini protocol
* constructors for the various kinds of gemini protocol responses
* a helper for building a gemini-suitable TLS config
* a Client implementation
* a Server which can run your Handlers.
The primary text formats for those protocols have higher-level support provided in sub-packages:
## gus/gemini/gemtext
* gus/gemini/gemtext supports parsing gemtext and getting direct programmatic access to its AST. Deeper sub-packages provide converters to other formats (markdown and HTML) with overridable templates.
* gus/gopher/gophermap similarly parses the gophermap format and provides access to its AST.
The gemtext package provides a parser and converters for gemtext documents. It exposes an AST representation for parsed gemtext, and functions to write that AST out as other formats (currently markdown and HTML are supported, but more are planned).
## Logging
Gus borrows the logging interface from go-kit.
=> [The logger interface from go-kit/log.](https://pkg.go.dev/github.com/go-kit/log#Logger)
The gus/logging package provides everything you need to get a good basic start to producing helpful logs.
* A request-logging middleware with common diagnostics (time, duration, url, status codes, response body lengths)
* A simple constructor of useful default loggers at various levels. They output colorful logfmt lines to stdout.
## gus/contrib/*
@ -38,7 +48,6 @@ This is where useful building blocks themselves start to come in. Sub-packages o
The sub-packages include:
* log contains a simple request-logging middleware
* fs has handlers that make file servers possible: serve files, build directory listings, etc
* cgi includes handlers which can execute CGI programs
* sharedhost which provides means of handling /~username URLs
@ -69,7 +78,7 @@ There's lots still to do, and contributions are very welcome!
=> [send me an email directly,](mailto:tjp@ctrl-c.club)
or poke me on IRC: I'm @tjp on irc.tilde.chat, and you'll find me in #gemini
or poke me on IRC: I'm @tjp on irc.tilde.chat where you'll find me in #gemini
------------------------