From 3834e49c90c39f4c95e3b9e7bb52b35204a75625 Mon Sep 17 00:00:00 2001 From: Stefan Majewsky Date: Sun, 28 Jan 2018 22:47:35 +0100 Subject: sketch out how requests could work --- README.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) (limited to 'README.md') diff --git a/README.md b/README.md index 823537c..dc82a13 100644 --- a/README.md +++ b/README.md @@ -61,3 +61,33 @@ handle(err) From this point, follow the [API documentation](https://godoc.org/github.com/majewsky/schwift) for what you can do with the `schwift.Account` object. + +## Why another Swift client library? + +The most popular Swift client library is [`ncw/swift`](https://github.com/ncw/swift). I have [used +it](https://github.com/docker/distribution/pull/2441) [extensively](https://github.com/sapcc/swift-http-import) and my +main gripe with it is that its API is designed around single tasks (like "get content of body as string") which are each +modeled as single functions. Since you cannot add arguments to an existing function without breaking backwards +compatibility, this means that if the existing functions do not cover your usecase, you have to add another function to +do basically the same thing. When you're trying to do something that's not one of the 10 most common things, you're +going to run into dead ends where the API does not allow you do specify that one URL parameter that you need. Like that +one day [when I filed five issues in a row because every function in the API that I tried turned out to be missing +something](https://github.com/ncw/swift/issues?utf8=%E2%9C%93&q=is%3Aissue+author%3Amajewsky+created%3A2017-11). + +This library uses Gophercloud for authentication (which solves one problem that ncw/swift has, namely that you cannot +use the Keystone token that ncw/swift fetches for talking to other OpenStack services), but besides the auth code, it +avoids pretty much all other parts of Gophercloud, because it too has fatal design flaws: + +- The API is modeled around individual requests and responses, which means that there will probably never be support for + advanced features like large objects unless you're willing to do all the footwork yourself. +- The built-in error handling paves over any useful error messages that the server might return. For example, when you + get a 404 response, `err.Error()` only says [`Resource not + found`](https://github.com/gophercloud/gophercloud/blob/4a3f5ae58624b68283375060dad06a214b05a32b/errors.go#L112). To + get the actual server error message, you have to use `err.(*gophercloud.ErrUnexpectedResponseCode).Body` which is + absolutely obvious. +- The implementation is quite unidiomatic. It all looks like a Java developer's first Go project. For example, to resume + the error handling example, [all of + this](https://github.com/gophercloud/gophercloud/blob/4a3f5ae58624b68283375060dad06a214b05a32b/errors.go#L65-L178) + should be deleted without replacement because `ErrUnexpectedResponseCode` does the same without paving over the server + error message. Most other types in that module should probably be deleted as well (there is no plausible reason for + requiring all error types to inherit from a `BaseError`; after all, this is Go, not Java). -- cgit v1.2.3