web_function 0.5.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c451f0b269e4441e7982d789b8fb4a4d827543e9d9f8769aa2bc4350a667435b
-  data.tar.gz: 1fe79584e5f3cd31f5792c63c7fed415cc999ccafbf736bb41f8a024c0c65690
+  metadata.gz: 4f6b3fc6e012055cb40b8d2e51d4118b0d6d6cff8fdb62abde22790774cf787d
+  data.tar.gz: 6f795bf7794369f8fa4699c31f50af7c768b2fbd287069f3d3aca29c2da89174
 SHA512:
-  metadata.gz: 07f4280c1e265f99898667f4860f1772088ae729fc41080ab27e2f6db1bd88d3611efc5314d2ab6b43c222c38be2f612772fd4167c41f8a5d17db6dd06aefa7c
-  data.tar.gz: 0b529bea38f2866549209a7d01fa5a8b126b17b79c4791ebf60ebd2407136dfabc7657c82efebea3275bbf9ad9b686943d797ccd3b397e2c6e124aab338a307f
+  metadata.gz: 57b90f3d4d8205511ee78a0b963b35a72a535681ddb5cb6d53d942f1429222f55d8e51f48c04ee4278cb75f8766b4f3b805988e5e55c94fa0aacf14d0a803b61
+  data.tar.gz: 1c71b7c581ecfd14435c1b57251d10c8bb4199ae82b5c0d1b88e41ff85afcc072faea3b968e6f1441379740de4cd904d65414fb71eb9ac4aff93184178592a8a

data/README.md

@@ -1,39 +1,460 @@
-# WebFunction
+# web_function
 
-TODO: Delete this and the text below, and describe your gem
+A [Web Function](https://webfunction.org) client for Ruby.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/web_function`. To experiment with that code, run `bin/console` for an interactive prompt.
+Web Function is a way to design APIs. There are no verbs and no nested URLs. You
+call an endpoint with a POST request, the path names the action, and the JSON
+body carries the data. This gem lets you call those endpoints from Ruby.
+
+```ruby
+client = WebFunction::Client.from_package_endpoint("https://api.example.com/package")
+
+client.find_user(id: "123")
+# => { "id" => "123", "name" => "Ada" }
+```
+
+## Table of contents
+
+- [Why Web Function](#why-web-function)
+- [Installation](#installation)
+- [Quick start](#quick-start)
+- [Clients](#clients)
+- [Calling endpoints](#calling-endpoints)
+- [Authentication](#authentication)
+- [Versioning](#versioning)
+- [Inspecting a package](#inspecting-a-package)
+- [Error handling](#error-handling)
+- [Pipelining](#pipelining)
+- [Custom HTTP client](#custom-http-client)
+- [Low-level requests](#low-level-requests)
+- [Command line tool](#command-line-tool)
+- [Development](#development)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why Web Function
+
+A Web Function API has a few simple rules:
+
+- Every call is an HTTP POST.
+- The request body is a JSON object.
+- The response body is any JSON value.
+- A `200` status means success and the body is the return value.
+- A `400` status means the request was bad and the body explains why.
+- Any other status is an error you handle yourself.
+
+On top of that, an API can publish a **package**. A package is a JSON document
+that lists the endpoints, their arguments, their return types, and their docs.
+This gem reads a package and gives you a client that calls those endpoints as if
+they were Ruby methods.
+
+You can read the full specification at [webfunction.org](https://webfunction.org).
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Add the gem to your project:
+
+```bash
+bundle add web_function
+```
 
-Install the gem and add to the application's Gemfile by executing:
+Or install it on its own:
 
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install web_function
+```
+
+The gem needs Ruby 3.1 or newer.
+
+## Quick start
+
+Point a client at a package URL and start calling endpoints:
+
+```ruby
+require "web_function"
+
+client = WebFunction::Client.from_package_endpoint("https://api.example.com/package")
+
+# An endpoint named "list-items" becomes the method "list_items".
+items = client.list_items(limit: 10)
+# => [{ "id" => 1 }, { "id" => 2 }]
+
+# Pass a bearer token for endpoints that need authentication.
+secure = WebFunction::Client.from_package_endpoint(
+  "https://api.example.com/package",
+  bearer_auth: "my-token",
+)
+
+secure.create_item(name: "Notebook")
+# => { "id" => 3, "name" => "Notebook" }
+```
+
+## Clients
+
+A `WebFunction::Client` wraps a package and turns each endpoint into a method.
+
+You usually build a client from a package URL. The gem fetches the package,
+reads its endpoints, and returns a ready client:
+
+```ruby
+client = WebFunction::Client.from_package_endpoint("https://api.example.com/package")
+```
+
+If you already have a package in memory, build the client from that instead.
+This avoids the extra request:
+
+```ruby
+package = WebFunction::Package.from_hash(
+  "base_url" => "https://api.example.com/",
+  "endpoints" => [
+    { "name" => "list-items" },
+    { "name" => "create-item" },
+  ],
+)
+
+client = WebFunction::Client.from_package(package)
+```
+
+Both builders accept the same options:
+
+| Option | Description |
+| --- | --- |
+| `bearer_auth` | A bearer token sent with every call. |
+| `version` | A version string sent in the `Api-Version` header. |
+| `pipelined` | When `true`, calls are batched into one request. See [Pipelining](#pipelining). |
+
+You can also overwrite these using the `Client#bearer_auth=`, `Client#version=`
+and `Client#pipeline=` attribute writers after having instantiated a client.
+
+## Calling endpoints
+
+Endpoint names use dashes, like `list-items`. The client exposes them as Ruby
+methods with underscores, like `list_items`. You pass arguments as keywords:
+
+```ruby
+client.list_items(limit: 10, offset: 20)
+```
+
+The return value is the parsed JSON response. It can be a hash, an array, a
+string, a number, a boolean, or `nil`.
+
+```ruby
+client.get_count          # => 42
+client.list_items         # => [{ "id" => 1 }]
+client.find_user(id: "1") # => { "id" => "1", "name" => "Ada" }
+```
+
+If you prefer to call an endpoint by its name, use `call`:
+
+```ruby
+client.call("list-items", limit: 10)
+```
+
+Calling an endpoint that the package does not define raises `NoMethodError`:
+
+```ruby
+client.does_not_exist
+# => NoMethodError
+```
+
+## Authentication
+
+Some endpoints need a bearer token. Pass it when you build the client and the
+gem adds an `Authorization: Bearer <token>` header to every call:
+
+```ruby
+client = WebFunction::Client.from_package_endpoint(
+  "https://api.example.com/package",
+  bearer_auth: "my-token",
+)
+
+client.list_orders
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+The gem does not handle login. How you obtain the token is up to you. To find
+out whether an endpoint needs a token, check its `bearer_auth?` flag:
+
+```ruby
+endpoint = client.package.endpoint("list-orders")
+endpoint.bearer_auth?    # => true
+endpoint.capture_bearer? # => false
+```
+
+## Versioning
+
+A versioned package selects its version through the `Api-Version` header. Pass a
+version string when you build the client:
+
+```ruby
+client = WebFunction::Client.from_package_endpoint(
+  "https://api.example.com/package",
+  version: "2024-01-01",
+)
+```
+
+You can ask a package whether it is versioned and which versions it offers:
+
+```ruby
+package = client.package
+package.versioned? # => true
+package.version    # => "2024-01-01"
+package.versions   # => ["2023-06-01", "2024-01-01"]
+```
+
+## Inspecting a package
+
+A package describes itself. You can read its metadata, walk its endpoints, and
+look at the arguments and outputs of each one. This is useful for building docs
+or for checking a call before you make it.
+
+```ruby
+package = client.package
+
+package.name      # => "Example API"
+package.base_url  # => "https://api.example.com/"
+package.docs      # => "Markdown documentation for the package."
+package.endpoints # => [#<WebFunction::Endpoint ...>, ...]
+```
+
+Look up a single endpoint by name. Underscores and dashes both work:
+
+```ruby
+endpoint = package.endpoint("find-user")
+# Same as:
+endpoint = package.endpoint(:find_user)
+
+endpoint.name    # => "find-user"
+endpoint.docs    # => "Retrieves user data."
+endpoint.returns # => ["object"]
+endpoint.group   # => "Users"
+```
+
+Each endpoint lists the arguments it takes:
+
+```ruby
+endpoint.arguments
+# => [#<WebFunction::Argument ...>]
+
+id = endpoint.argument("id")
+id.name      # => "id"
+id.type      # => "string"
+id.required? # => true
+id.optional? # => false
+id.choices   # => []
+id.docs      # => "Identifier of the user."
+```
+
+It also lists the attributes it returns when the return type is an object:
+
+```ruby
+name = endpoint.attribute("name")
+name.name      # => "name"
+name.type      # => "string"
+name.nullable? # => false
+name.values    # => []
+```
+
+You can call an endpoint object directly once it belongs to a client:
+
+```ruby
+endpoint = client.package.endpoint("find-user")
+endpoint.call(id: "123")
+# => { "id" => "123", "name" => "Ada" }
+```
+
+## Error handling
+
+Every error this gem raises inherits from `WebFunction::Error`. Each error
+carries a `code` and optional `details`.
+
+```ruby
+begin
+  client.find_user(id: "missing")
+rescue WebFunction::Error => e
+  e.code    # => "USER_NOT_FOUND"
+  e.message # => "No user with that id."
+  e.details # => { "id" => "missing" }
+end
+```
+
+These are the error classes:
+
+| Class | Raised when |
+| --- | --- |
+| `WebFunction::BadRequestError` | The server replied with status `400`. |
+| `WebFunction::UnexpectedStatusCodeError` | The server replied with a status other than `200` or `400`. |
+| `WebFunction::JsonParseError` | The response body was not valid JSON. |
+| `WebFunction::UnresolvedPromiseError` | A pipeline promise was read before it resolved. |
+
+When the server returns a `400`, the body is an error triple. A triple is a
+JSON array with three parts: a code, a message, and details. The gem reads the
+triple and fills in the error:
+
+```json
+["USER_NOT_FOUND", "No user with that id.", { "id": "missing" }]
+```
+
+```ruby
+rescue WebFunction::BadRequestError => e
+  e.code    # => "USER_NOT_FOUND"
+  e.message # => "No user with that id."
+  e.details # => { "id" => "missing" }
+```
+
+If the body is not a triple, the gem still raises `BadRequestError` with the
+code `WFN_BAD_REQUEST_ERROR` and puts the raw body in `details`.
+
+An endpoint can document the errors it may return. Read them when the endpoint
+uses the `error_triple` flag:
+
+```ruby
+endpoint.errors
+# => [#<WebFunction::DocumentedError code="USER_NOT_FOUND" ...>]
+
+error = endpoint.error("USER_NOT_FOUND")
+error.code # => "USER_NOT_FOUND"
+error.docs # => "Returned when no user matches the id."
+```
+
+The package can document shared errors too:
+
+```ruby
+package.errors
+package.error("RATE_LIMITED")
+```
+
+## Pipelining
+
+Pipelining sends several calls in one HTTP request. The server runs them in
+order and you can feed the output of one call into the next. This cuts the
+number of round trips.
+
+Build a pipelined client and each call returns a `WebFunction::Promise` instead
+of a value. A promise stands in for a result that does not exist yet:
+
+```ruby
+client = WebFunction::Client.from_package_endpoint(
+  "https://api.example.com/package",
+  pipelined: true,
+)
+
+user  = client.find_user(id: "123")  # => a Promise
+order = client.create_order(user_id: user["id"]) # uses the first result
+
+order.resolve
+# => { "id" => "order-1", "user_id" => "123" }
+```
+
+Reading `user["id"]` before the call runs does not return a value. It returns a
+path into the future result. The gem sends that path to the server, and the
+server fills it in when it runs the second call. Calling `resolve` runs the
+whole pipeline and returns the value.
+
+Once a pipeline runs, every promise from that batch holds its value:
+
+```ruby
+user.resolve  # runs the pipeline
+order.value   # already available, no extra request
+```
+
+You can also drive a pipeline by hand with `WebFunction::Pipeline`. Each step is
+a hash with a `url`, `headers`, and `body`:
+
+```ruby
+pipeline = WebFunction::Pipeline.new("https://api.example.com/run-pipeline")
+
+pipeline.add_step(url: "https://api.example.com/a", headers: {}, body: {})
+pipeline.add_step(url: "https://api.example.com/b", headers: {}, body: {})
+
+pipeline.execute(returns: :all)
+# => [{ "a" => 1 }, { "b" => 2 }]
+```
+
+The `returns` option controls what comes back:
+
+- `:all` returns every step result as an array. This is the default.
+- `:last` returns only the last step result.
+- A JSONPath string returns the value at that path, for example `"$[0].id"`.
+
+## Custom HTTP client
+
+By default the gem makes requests with [Excon](https://github.com/excon/excon).
+You can swap in any HTTP client by setting `WebFunction::Request.http_client` to
+an object that responds to `call`.
+
+The object receives the URL, the headers, and the JSON body. It must return a
+two-element array of the status code and the raw response body:
+
+```ruby
+WebFunction::Request.http_client = ->(url, headers, body) do
+  response = MyHttp.post(url, headers: headers, body: body)
+  [response.status, response.body]
+end
+```
+
+This is also handy in tests, where you can return a canned response without
+making a real request:
+
+```ruby
+WebFunction::Request.http_client = ->(_url, _headers, _body) do
+  [200, JSON.generate({ "id" => "123" })]
+end
+```
+
+## Low-level requests
+
+If you do not need a package, you can call a single endpoint URL directly with
+`WebFunction::Request`:
+
+```ruby
+WebFunction::Request.execute(
+  "https://api.example.com/find-user",
+  bearer_auth: "my-token",
+  version: "2024-01-01",
+  args: { id: "123" },
+)
+# => { "id" => "123", "name" => "Ada" }
+```
+
+The request adds the standard headers, posts the JSON body, and parses the
+response. It raises the same errors described in [Error handling](#error-handling).
+
+## Command line tool
+
+The gem ships with a `wfn` command. Use it to call an endpoint from the shell.
+Arguments go in a JSON string:
 
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+wfn call https://api.example.com/find-user '{"id":"123"}'
 ```
 
-## Usage
+Pass a bearer token with `--auth` and a version with `--version`:
+
+```bash
+wfn call --auth my-token --version 2024-01-01 \
+  https://api.example.com/list-orders '{}'
+```
 
-TODO: Write usage instructions here
+The command prints the response as formatted JSON. On an error it prints the
+code, the message, and the details, then exits with a non-zero status.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After you check out the repo, run `bin/setup` to install dependencies. Then run
+`rake test` to run the tests. Run `bin/console` for a prompt where you can
+experiment with the code.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To install the gem on your machine, run `bundle exec rake install`. To release a
+new version, update the version in `lib/web_function/version.rb`, then run
+`bundle exec rake release`. This creates a git tag, pushes the commits and the
+tag, and pushes the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/web_function.
+Bug reports and pull requests are welcome on GitHub at
+[github.com/robinclart/web_function](https://github.com/robinclart/web_function).
 
 ## License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This gem is open source under the terms of the
+[MIT License](https://opensource.org/licenses/MIT).

data/exe/wfn

@@ -8,10 +8,17 @@ require "json"
 #   wfn call --auth token endpoint_url key1=value1 [key2=value2 ...]
 
 auth_token = nil
-auth_idx = ARGV.index("--auth")
-if auth_idx
-  auth_token = ARGV[auth_idx + 1]
-  ARGV.slice!(auth_idx, 2)
+auth_index = ARGV.index("--auth")
+if auth_index
+  auth_token = ARGV[auth_index + 1]
+  ARGV.slice!(auth_index, 2)
+end
+
+version = nil
+version_index = ARGV.index("--version")
+if version_index
+  version = ARGV[version_index + 1]
+  ARGV.slice!(version_index, 2)
 end
 
 command = ARGV[0]
@@ -22,7 +29,7 @@ when "call"
   args = JSON.parse(ARGV[2] || "{}")
 
   begin
-    response = WebFunction::Endpoint.invoke(endpoint_url, bearer_auth: auth_token, args: args)
+    response = WebFunction::Request.execute(endpoint_url, bearer_auth: auth_token, version: version, args: args)
     puts JSON.pretty_generate(response)
   rescue WebFunction::Error => e
     puts e