ished 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ff919149cef62f290766619ba426082209a755ad8f1aeaa1183d3f365abdadb9
+  data.tar.gz: ee8441ea5695a4854c849e99195b1d065d6795f1b1c00e7d357197d2781edfaf
+SHA512:
+  metadata.gz: 824470231465a80d034a4121939cc9965ea97b85e8331bc0c0bf9a9370b72f8a4517989609d04306a76815c2788af0389883288c5cd0a9d2c46fa832ff2cf4a8
+  data.tar.gz: ff522626dbcc0dac59ef0605416979e13eaf3215fec79b3ce4c6e6f95ca6dd10bbd11a26c275424f955abf8aee2755f6b67c9a8a3f8fbfbf08c986ad48f9fae7

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/lib/ished/grid.rb

@@ -0,0 +1,144 @@
+# IshedDB's files from Ruby, as the mongo gem's Mongo::Grid::FSBucket (database.fs): upload_from_stream,
+# open_upload_stream, download_to_stream(_by_name), open_download_stream(_by_name), find, delete, rename, drop — the
+# same names and arguments. The bytes go to IshedDB in pieces (a resumable upload, as Cloud Storage's) and come back
+# as a stream; a file's document is one of the collection <bucket>.files. IshedDB's own: signed_url for a browser.
+
+require "stringio"
+
+module Ished
+  class FSBucket
+    PIECE = 8 * 1024 * 1024 # one request (a multiple of IshedDB's 256 KB segments)
+
+    attr_reader :bucket_name
+
+    # A file being written, as the gem's upload stream: write, then close (or the block's end); its file_id.
+    class UploadStream
+      attr_reader :file_id
+
+      def initialize(bucket, filename, options)
+        @bucket = bucket
+        @filename = filename
+        @options = options
+        @buffer = StringIO.new("".b)
+        @closed = false
+      end
+
+      def write(data)
+        raise Error.new("invalid-argument", "this upload stream is closed") if @closed
+
+        @buffer.write(data.b)
+        self
+      end
+
+      def close
+        return @file_id if @closed
+
+        @buffer.rewind
+        @file_id = @bucket.send(:upload, @filename, @buffer, @options)
+        @closed = true
+        @file_id
+      end
+
+      def closed? = @closed
+    end
+
+    def initialize(database, call, raw, path, bucket_name: "fs")
+      raise Error.new("invalid-argument", 'bucket_name: 1 to 94 letters, digits, "_", "-" or "."') unless bucket_name.to_s.match?(/\A[A-Za-z0-9_-][A-Za-z0-9_.-]{0,93}\z/)
+
+      @database = database
+      @call = call
+      @raw = raw
+      @bucket_name = bucket_name.to_s
+      @path = "#{path}/buckets/#{Ished.segment(@bucket_name)}"
+    end
+
+    # ---- writing ----------------------------------------------------------------------------------------------------
+
+    # As the gem's upload_from_stream(filename, io, metadata:, file_id:): the file's id.
+    def upload_from_stream(filename, io, options = {}) = upload(filename, io.is_a?(String) ? StringIO.new(io.b) : io, options)
+
+    # As the gem's open_upload_stream(filename) { |stream| stream.write(...) }: the stream (closed after the block).
+    def open_upload_stream(filename, options = {})
+      stream = UploadStream.new(self, filename, options)
+      return stream unless block_given?
+
+      yield stream
+      stream.close
+      stream
+    end
+
+    # ---- reading ----------------------------------------------------------------------------------------------------
+
+    # As the gem's download_to_stream(id, io): the bytes written to io as they come.
+    def download_to_stream(file_id, io)
+      document(file_id)
+      @raw.call(:get, "#{@path}/files/#{Ished.segment(file_id.to_s)}:download", nil, {}, auth: true) { |chunk| io.write(chunk) }
+      io
+    end
+
+    # As the gem's open_download_stream(id) { |stream| stream.read }: a stream of the file's bytes.
+    def open_download_stream(file_id)
+      io = download_to_stream(file_id, StringIO.new("".b))
+      io.rewind
+      block_given? ? yield(io) : io
+    end
+
+    # As the gem: revision 0 the first one sent, -1 the last one (default).
+    def download_to_stream_by_name(filename, io, revision: -1) = download_to_stream(by_name(filename, revision), io)
+
+    def open_download_stream_by_name(filename, revision: -1, &block) = open_download_stream(by_name(filename, revision), &block)
+
+    # ---- the files' documents -----------------------------------------------------------------------------------------
+
+    # As the gem's find(selector): a view of the files' documents (the collection <bucket>.files).
+    def find(selector = {}, options = {}) = @database.collection("#{@bucket_name}.files").find(selector, options)
+
+    def find_one(selector = {}) = find(selector).limit(1).first
+
+    # As the gem's delete(id): the file's document and its bytes.
+    def delete(file_id) = @call.call(:post, "#{@path}/files/#{Ished.segment(file_id.to_s)}:delete", {}) && nil
+
+    def rename(file_id, new_filename) = @call.call(:post, "#{@path}/files/#{Ished.segment(file_id.to_s)}:rename", { "filename" => new_filename }) && nil
+
+    # As the gem's drop: every file of the bucket, and its <bucket>.files collection.
+    def drop = @call.call(:post, "#{@path}:drop", {}) && nil
+
+    # IshedDB's own: a signed address for a browser (no key in it), as Cloud Storage's signed URLs: url, expiresAt.
+    def signed_url(file_id, expires_in: 3600, disposition: "attachment") = @call.call(:post, "#{@path}/files/#{Ished.segment(file_id.to_s)}:signUrl", { "expiresIn" => expires_in, "disposition" => disposition })
+
+    private
+
+    def document(file_id)
+      find_one({ _id: file_id }) || raise(Error.new("not-found", "no file #{file_id} in the bucket #{@bucket_name}", 404))
+    end
+
+    def by_name(filename, revision)
+      view = find({ filename: filename }).sort(uploadDate: revision >= 0 ? 1 : -1).skip(revision >= 0 ? revision : -revision - 1).limit(1)
+      (view.first || raise(Error.new("not-found", "no revision #{revision} of the file #{filename} in the bucket #{@bucket_name}", 404)))["_id"]
+    end
+
+    # Sends io in pieces of 8 MB; the length told with the last one.
+    def upload(filename, io, options)
+      body = { "filename" => filename, "length" => nil }
+      body["id"] = options[:file_id].to_s if options[:file_id]
+      body["metadata"] = Ished.to_wire(options[:metadata]) if options[:metadata]
+      body["contentType"] = options[:content_type] if options[:content_type]
+      piece = io.read(PIECE) || "".b
+      body["length"] = 0 if piece.empty?
+      started = @call.call(:post, "#{@path}/uploads", body)
+      return started["id"] if started.key?("file")
+
+      at = 0
+      loop do
+        following = io.read(PIECE)
+        last = following.nil? || following.empty?
+        total = last ? (at + piece.bytesize).to_s : "*"
+        @raw.call(:put, started["uploadUrl"], piece, { "Content-Range" => "bytes #{at}-#{at + piece.bytesize - 1}/#{total}", "Content-Type" => "application/octet-stream" }, auth: false)
+        at += piece.bytesize
+        return started["id"] if last
+
+        piece = following
+      end
+    end
+  end
+end

data/lib/ished.rb

@@ -0,0 +1,540 @@
+# IshedDB for Ruby, written as the mongo gem is: client.use("clinique")[:patients].find(ville: "Dakar").sort(age: -1).to_a
+# Only Ruby's standard library. The key never travels but over HTTPS (or to this machine). Values: Time <-> dates,
+# Integer beyond 2**53 <-> big integers, binary Strings (ASCII-8BIT) <-> bytes.
+require "json"
+require "net/http"
+require "time"
+require "uri"
+
+module Ished
+  MAX_DOCUMENTS = 100_000
+  SAFE_INT = (2**53) - 1
+
+  class Error < StandardError
+    attr_reader :code, :status
+    def initialize(code, message, status = nil)
+      super("#{code}: #{message}")
+      @code = code
+      @status = status
+    end
+  end
+
+  InsertOneResult = Struct.new(:inserted_id)
+  InsertManyResult = Struct.new(:inserted_ids)
+  UpdateResult = Struct.new(:matched_count, :modified_count, :upserted_id)
+  DeleteResult = Struct.new(:deleted_count)
+  BulkWriteResult = Struct.new(:inserted_count, :matched_count, :modified_count, :deleted_count, :upserted_count, :upserted_ids)
+
+  def self.to_wire(value)
+    case value
+    when Time, DateTime then { "~date" => value.to_time.utc.iso8601(3) }
+    when Integer then value.abs <= SAFE_INT ? value : { "~int" => value.to_s }
+    when String then value.encoding == Encoding::BINARY ? { "~bytes" => [value].pack("m0") } : value
+    when Symbol then value.to_s
+    when Hash then value.to_h { |k, v| [k.to_s, to_wire(v)] }
+    when Array then value.map { |v| to_wire(v) }
+    when Float, true, false, nil then value
+    else raise Error.new("invalid-argument", "a value of class #{value.class} cannot be kept")
+    end
+  end
+
+  def self.from_wire(value)
+    case value
+    when Array then value.map { |v| from_wire(v) }
+    when Hash
+      if value.size == 1
+        k, v = value.first
+        return Time.iso8601(v) if k == "~date"
+        return Integer(v) if k == "~int"
+        return v.unpack1("m0") if k == "~bytes"
+      end
+      value.to_h { |k, v| [k, from_wire(v)] }
+    else value
+    end
+  end
+
+  # As the mongo gem's view: .sort, .limit, .skip, .projection, then .to_a, .each or .first. Read 1000 at a time.
+  class View
+    include Enumerable
+
+    def initialize(call, path, filter, options = {})
+      @call = call
+      @path = path
+      @filter = filter || {}
+      @options = options
+    end
+
+    def sort(spec) = with(sort: spec)
+    def limit(n) = with(limit: n)
+    def skip(n) = with(skip: n)
+    def projection(spec) = with(projection: spec)
+
+    def each(&block)
+      to_a.each(&block)
+    end
+
+    def first
+      limit(1).to_a.first
+    end
+
+    # As the mongo gem's view.explain(verbosity: …): the find's plan (:query_planner, :execution_stats or
+    # :all_plans_execution, the default), in MongoDB's shape.
+    def explain(verbosity: nil)
+      find = { "find" => URI.decode_www_form_component(@path.split("/").last), "filter" => Ished.to_wire(@filter) }
+      find["sort"] = Ished.to_wire(@options[:sort]) if @options[:sort]
+      find["projection"] = Ished.to_wire(@options[:projection]) if @options[:projection]
+      find["skip"] = @options[:skip] if @options[:skip].to_i.positive?
+      find["limit"] = @options[:limit] if @options[:limit].to_i.positive?
+      body = { "explain" => find }
+      body["verbosity"] = verbosity.to_s.gsub(/_(\w)/) { Regexp.last_match(1).upcase } if verbosity
+      @call.call(:post, "#{@path}:explain", body)
+    end
+
+    def to_a
+      limit = @options[:limit].to_i
+      out = []
+      token = nil
+      loop do
+        want = limit.positive? ? [1000, limit - out.size].min : 1000
+        body = { "filter" => Ished.to_wire(@filter), "limit" => want }
+        # The next page starts after the last one read (its token), never at an offset that moves with writes.
+        if token then body["pageToken"] = token else body["skip"] = @options[:skip].to_i end
+        body["sort"] = Ished.to_wire(@options[:sort]) if @options[:sort]
+        body["projection"] = Ished.to_wire(@options[:projection]) if @options[:projection]
+        page = @call.call(:post, "#{@path}:find", body)
+        out.concat(page["documents"].map { |d| Ished.from_wire(d) })
+        token = page["nextPageToken"]
+        return out if token.nil? || (limit.positive? && out.size >= limit)
+        raise Error.new("resource-exhausted", "more than #{MAX_DOCUMENTS} documents: narrow the filter") if out.size >= MAX_DOCUMENTS
+      end
+    end
+
+    private
+
+    def with(change) = View.new(@call, @path, @filter, @options.merge(change))
+  end
+
+  class Collection
+    def initialize(call, path, options = {})
+      @call = call
+      @path = path
+      @options = options
+    end
+
+    # As the mongo gem's collection.create: an empty collection, or a view when made with view_on: and pipeline:
+    # (client[:name, view_on: "source", pipeline: […]].create).
+    # Its validator too, as the gem's: client[:name, validator: { "$jsonSchema" => … }, validation_level: "moderate",
+    # validation_action: "warn"].create.
+    def create
+      body = {}
+      body["viewOn"] = @options[:view_on].to_s if @options[:view_on]
+      body["pipeline"] = Ished.to_wire(@options[:pipeline]) if @options[:pipeline]
+      body["validator"] = Ished.to_wire(@options[:validator]) if @options[:validator]
+      body["validationLevel"] = @options[:validation_level].to_s if @options[:validation_level]
+      body["validationAction"] = @options[:validation_action].to_s if @options[:validation_action]
+      @call.call(:post, "#{@path}:create", body)
+      self
+    end
+
+    # As the gem's collection.drop: the collection and its documents, or the view.
+    def drop = @call.call(:post, "#{@path}:drop", {})["ok"] == 1
+
+    def find(filter = {}, options = {}) = View.new(@call, @path, filter, options)
+
+    def count_documents(filter = {})
+      @call.call(:post, "#{@path}:countDocuments", { "filter" => Ished.to_wire(filter) })["count"]
+    end
+
+    # As the mongo gem's aggregate: the pipeline run by the server; every result, read 1000 at a time.
+    def aggregate(pipeline, _options = {})
+      out = []
+      skip = 0
+      loop do
+        page = @call.call(:post, "#{@path}:aggregate", { "pipeline" => Ished.to_wire(pipeline), "limit" => 1000, "skip" => skip })
+        out.concat(page["documents"].map { |d| Ished.from_wire(d) })
+        return out unless page["more"]
+        raise Error.new("resource-exhausted", "more than #{MAX_DOCUMENTS} documents: add $limit") if out.size >= MAX_DOCUMENTS
+        skip += 1000
+      end
+    end
+
+    # As the mongo gem's bulk_write: [{ insert_one: doc }, { update_one: { filter:, update:, upsert: } }, { update_many: … },
+    # { replace_one: { filter:, replacement: } }, { delete_one: { filter: } }, { delete_many: … }]; ordered: false goes on.
+    def bulk_write(requests, options = {})
+      ops = requests.map do |request|
+        name, args = request.first
+        camel = name.to_s.gsub(/_(\w)/) { Regexp.last_match(1).upcase }
+        { camel => (camel == "insertOne" ? { "document" => args } : args.transform_keys(&:to_s)) }
+      end
+      r = @call.call(:post, "#{@path}:bulkWrite", { "operations" => Ished.to_wire(ops), "ordered" => options.fetch(:ordered, true) })
+      BulkWriteResult.new(r["insertedCount"], r["matchedCount"], r["modifiedCount"], r["deletedCount"], r["upsertedCount"], r["upsertedIds"].transform_keys(&:to_i))
+    end
+
+    # The collection's number of documents, from the statistics (at once on a big collection).
+    def estimated_document_count
+      @call.call(:post, "#{@path}:estimatedDocumentCount", {})["count"]
+    end
+
+    # The different values of a field among the documents found (a list's items one by one).
+    def distinct(field_name, filter = {})
+      @call.call(:post, "#{@path}:distinct", { "key" => field_name.to_s, "filter" => Ished.to_wire(filter) })["values"].map { |v| Ished.from_wire(v) }
+    end
+
+    def insert_one(document)
+      InsertOneResult.new(@call.call(:post, "#{@path}:insertOne", { "document" => Ished.to_wire(document) })["insertedId"])
+    end
+
+    def insert_many(documents)
+      ids = []
+      documents.each_slice(1000) do |slice|
+        r = @call.call(:post, "#{@path}:insertMany", { "documents" => slice.map { |d| Ished.to_wire(d) } })
+        ids.concat((0...r["insertedIds"].size).map { |i| r["insertedIds"][i.to_s] })
+      end
+      InsertManyResult.new(ids)
+    end
+
+    def update_one(filter, update, upsert: false) = change("updateOne", filter, "update", update, upsert)
+    def update_many(filter, update) = change("updateMany", filter, "update", update, nil)
+    def replace_one(filter, replacement, upsert: false) = change("replaceOne", filter, "replacement", replacement, upsert)
+
+    def delete_one(filter = {})
+      DeleteResult.new(@call.call(:post, "#{@path}:deleteOne", { "filter" => Ished.to_wire(filter) })["deletedCount"])
+    end
+
+    def delete_many(filter = {})
+      DeleteResult.new(@call.call(:post, "#{@path}:deleteMany", { "filter" => Ished.to_wire(filter) })["deletedCount"])
+    end
+
+    private
+
+    def change(method, filter, key, value, upsert)
+      body = { "filter" => Ished.to_wire(filter), key => Ished.to_wire(value) }
+      body["upsert"] = upsert unless upsert.nil?
+      r = @call.call(:post, "#{@path}:#{method}", body)
+      UpdateResult.new(r["matchedCount"], r["modifiedCount"], r["upsertedId"])
+    end
+  end
+
+  # As the driver's session: client.start_session { |s| s.with_transaction { coll.update_one(f, u, session: s) } }.
+  # The transaction is held by the server (60 seconds at most, 20 without a request); a conflict with another
+  # transaction answers "aborted", and with_transaction runs the block again.
+  class Session
+    def initialize(call, v1)
+      @call = call
+      @v1 = v1
+      @id = nil
+    end
+
+    def in_transaction? = !@id.nil?
+
+    def start_transaction(_options = {})
+      raise Error.new("failed-precondition", "a transaction is already started in this session") if @id
+
+      @id = @call.call(:post, "#{@v1}:beginTransaction", {})["transaction"]
+      nil
+    end
+
+    def bind(call)
+      header = { "X-Ished-Transaction" => @id }
+      ->(method, path, body) { call.call(method, path, body, header) }
+    end
+
+    def commit_transaction
+      raise Error.new("failed-precondition", "no transaction started in this session") unless @id
+
+      tx = @id
+      @id = nil
+      @call.call(:post, "#{@v1}:commit", { transaction: tx })
+      nil
+    end
+
+    def abort_transaction
+      return unless @id
+
+      tx = @id
+      @id = nil
+      @call.call(:post, "#{@v1}:rollback", { transaction: tx })
+      nil
+    rescue Error => e
+      raise unless e.code == "not-found" # already ended by the server (an error, or too long): nothing kept
+    end
+
+    def with_transaction(_options = {}, max_attempts: 5)
+      attempt = 0
+      begin
+        attempt += 1
+        start_transaction
+        out = yield self
+        commit_transaction
+        out
+      rescue Exception => e # rubocop:disable Lint/RescueException -- given back as it came
+        begin
+          abort_transaction
+        rescue Error
+          nil
+        end
+        retry if e.is_a?(Error) && e.code == "aborted" && attempt < max_attempts
+        raise
+      end
+    end
+
+    def end_session = abort_transaction
+  end
+
+  # session: as the driver's: the method (and the view it gives, read later) runs in the session's transaction.
+  module InSession
+    %i[find count_documents aggregate bulk_write estimated_document_count distinct insert_one insert_many
+       update_one update_many replace_one delete_one delete_many].each do |name|
+      define_method(name) do |*args, **kw, &block|
+        session = kw.delete(:session) if kw[:session].is_a?(Session)
+        last = args.last
+        if session.nil? && last.is_a?(Hash) && last[:session].is_a?(Session)
+          session = last[:session]
+          args = [*args[0...-1], last.except(:session)]
+        end
+        return super(*args, **kw, &block) unless session&.in_transaction?
+
+        Collection.new(session.bind(@call), @path).public_send(name, *args, **kw, &block)
+      end
+    end
+  end
+  Collection.prepend(InSession)
+
+  # As the driver's change stream: stream = coll.watch(pipeline, full_document: "updateLookup"); stream.each { |change| … }
+  # (blocks, waiting for changes), try_next, resume_token, close. Opened at once: the changes made from then on are
+  # seen. Each request waits up to max_await_time_ms (10 s by default, 20 s at most) on the server. A collection
+  # dropped or renamed ends its stream ("invalidate").
+  class ChangeStream
+    include Enumerable
+
+    def initialize(call, path, pipeline, options)
+      @call = call
+      @path = path
+      @body = { pipeline: Ished.to_wire(pipeline || []) }
+      @body[:fullDocument] = options[:full_document] if options[:full_document]
+      @body[:fullDocumentBeforeChange] = options[:full_document_before_change] if options[:full_document_before_change]
+      @body[:batchSize] = options[:batch_size] if options[:batch_size]
+      @wait = options[:max_await_time_ms] || 10_000
+      @position = options[:resume_after] || options[:start_after]
+      @at = options[:start_at_operation_time]
+      @token = @position
+      @buffer = []
+      @closed = false
+      fetch(0) if @position.nil? && @at.nil?
+    end
+
+    # The token to resume after the last change given (resume_after:).
+    def resume_token = @token
+    def closed? = @closed
+
+    # Each change as it comes, waiting for it, until the stream is closed.
+    def each
+      return to_enum(:each) unless block_given?
+
+      loop do
+        fetch(@wait) while @buffer.empty? && !@closed
+        break if @buffer.empty?
+
+        yield take
+      end
+    end
+
+    # The next change if one comes within a second (or max_await_time_ms, if shorter), else nil.
+    def try_next
+      fetch([@wait, 1000].min) if @buffer.empty? && !@closed
+      @buffer.empty? ? nil : take
+    end
+
+    def close
+      @closed = true
+      @buffer = []
+      nil
+    end
+
+    private
+
+    def fetch(wait)
+      body = @body.merge(maxAwaitTimeMS: wait)
+      if @position then body[:resumeAfter] = @position
+      elsif @at then body[:startAtOperationTime] = Ished.to_wire(@at)
+      end
+      r = @call.call(:post, @path, body)
+      @at = nil
+      @position = r["resumeToken"]
+      @buffer.concat(r["changes"].map { |c| Ished.from_wire(c) })
+      @token = r["resumeToken"] if @buffer.empty?
+    end
+
+    def take
+      change = @buffer.shift
+      @token = @buffer.empty? ? @position : change["_id"]
+      @closed = true if change["operationType"] == "invalidate"
+      change
+    end
+  end
+
+  # As the driver's index view: collection.indexes.create_one({ a: 1, b: -1 }, unique: true); create_many, each
+  # (Enumerable), drop_one, drop_all. A text index: create_one({ titre: "text" }, default_language: "french").
+  class IndexView
+    include Enumerable
+
+    OPTIONS = { unique: :unique, name: :name, partial_filter_expression: :partialFilterExpression, weights: :weights,
+                default_language: :default_language, expire_after: :expireAfterSeconds,
+                wildcard_projection: :wildcardProjection }.freeze
+
+    def initialize(call, path)
+      @call = call
+      @path = path
+    end
+
+    def create_one(keys, options = {}) = @call.call(:post, "#{@path}:createIndex", Ished.to_wire(spec(keys, options)))["name"]
+
+    def create_many(models)
+      specs = models.map { |m| spec(m[:key], m.reject { |k, _| k == :key }) }
+      @call.call(:post, "#{@path}:createIndexes", Ished.to_wire({ indexes: specs }))["names"]
+    end
+
+    def each(&block) = @call.call(:post, "#{@path}:listIndexes", {})["indexes"].map { |i| Ished.from_wire(i) }.each(&block)
+
+    def drop_one(name) = @call.call(:post, "#{@path}:dropIndex", { index: name }) && nil
+    def drop_all = @call.call(:post, "#{@path}:dropIndexes", {}) && nil
+
+    private
+
+    def spec(keys, options)
+      out = { key: keys.map { |k, v| [k.to_s, v] } }
+      options.each do |k, v|
+        name = OPTIONS[k.to_sym] or raise Error.new("invalid-argument", "index option #{k} is not offered")
+        out[name] = v
+      end
+      out
+    end
+  end
+
+  class Collection
+    # As the driver's collection.indexes: create_one, create_many, each, drop_one, drop_all.
+    def indexes = IndexView.new(@call, @path)
+
+    # As the driver's collection.watch: the collection's changes as they happen.
+    def watch(pipeline = [], options = {}) = ChangeStream.new(@call, "#{@path}:watch", pipeline, options)
+  end
+
+  class Database
+    def initialize(call, path, raw = nil)
+      @call = call
+      @path = path
+      @raw = raw
+    end
+
+    # As the gem's database.fs(bucket_name:): the files of a bucket, as GridFS (ished/grid.rb).
+    def fs(bucket_name: "fs") = FSBucket.new(self, @call, @raw, @path, bucket_name: bucket_name)
+
+    # As the driver's database.watch: the changes of every collection of the base.
+    def watch(pipeline = [], options = {}) = ChangeStream.new(@call, "#{@path}:watch", pipeline, options)
+
+    def collection(name, options = {}) = Collection.new(@call, "#{@path}/collections/#{URI.encode_www_form_component(name.to_s).gsub('+', '%20')}", options)
+    alias [] collection
+
+    def collection_names = @call.call(:get, "#{@path}/collections", nil).map { |c| c["name"] }
+
+    # As the gem's database.list_collections: name, type ("collection" or "view"), options, info.
+    def list_collections
+      @call.call(:get, "#{@path}/collections", nil).map do |c|
+        view = c["type"] == "view"
+        { "name" => c["name"], "type" => c["type"], "options" => view ? { "viewOn" => c["viewOn"], "pipeline" => c["pipeline"] } : {}, "info" => { "readOnly" => view } }
+      end
+    end
+
+    # As the gem's database.command: create, collMod (a view's viewOn and pipeline), drop, explain. Answers the
+    # reply's document.
+    def command(document) = Ished.from_wire(@call.call(:post, "#{@path}:runCommand", Ished.to_wire(document)))
+  end
+
+  class Client
+    def initialize(call, v1, raw = nil)
+      @call = call
+      @v1 = v1
+      @raw = raw
+    end
+
+    def use(name) = Database.new(@call, "#{@v1}/bases/#{URI.encode_www_form_component(name.to_s).gsub('+', '%20')}", @raw)
+    alias database use
+    alias db use
+
+    # As the driver's client.watch: the changes of the whole cluster.
+    def watch(pipeline = [], options = {}) = ChangeStream.new(@call, "#{@v1}:watch", pipeline, options)
+
+    # As the driver's client.list_databases: each base's name, sizeOnDisk and empty (a key limited to some: those).
+    def list_databases = @call.call(:get, "#{@v1}/bases", nil)["databases"]
+
+    # As the driver's client.database_names.
+    def database_names = list_databases.map { |d| d["name"] }
+    alias list_database_names database_names
+
+    def start_session
+      session = Session.new(@call, @v1)
+      return session unless block_given?
+
+      begin
+        yield session
+      ensure
+        session.end_session
+      end
+    end
+  end
+
+  # A client for one project (its key), in one of its clusters (by default the first, "Cluster0").
+  def self.connect(url, key, cluster: nil, timeout: 30)
+    uri = URI(url)
+    local = %w[127.0.0.1 localhost ::1].include?(uri.host)
+    raise Error.new("invalid-argument", "IshedDB is reached over HTTPS (plain HTTP only to this machine)") unless uri.scheme == "https" || (uri.scheme == "http" && local)
+    raise Error.new("invalid-argument", "a key ished_sk_… is needed") unless key.is_a?(String) && key.start_with?("ished_sk_")
+    raise Error.new("invalid-argument", 'cluster: 1 to 64 letters, digits or "-"') if cluster && cluster !~ /\A[A-Za-z0-9][A-Za-z0-9-]{0,63}\z/
+    root = url.chomp("/")
+    v1 = cluster ? "/v1/clusters/#{cluster}" : "/v1"
+    call = lambda do |method, path, body, extra = {}|
+      target = URI(root + path)
+      request = method == :get ? Net::HTTP::Get.new(target) : Net::HTTP::Post.new(target)
+      request["Authorization"] = "Bearer #{key}"
+      extra.each { |name, value| request[name] = value }
+      if body
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate(body)
+      end
+      response = Net::HTTP.start(target.host, target.port, use_ssl: target.scheme == "https", open_timeout: timeout, read_timeout: timeout) { |h| h.request(request) }
+      text = response.body.to_s.force_encoding("UTF-8")
+      unless response.is_a?(Net::HTTPSuccess)
+        err = (JSON.parse(text)["error"] rescue nil) || {}
+        raise Error.new(err["code"] || "internal", err["message"] || "HTTP #{response.code}", response.code.to_i)
+      end
+      text.empty? ? nil : JSON.parse(text)
+    end
+    # The files' bytes (ished/grid.rb): an upload session's own address (no key sent to it), or a download with the
+    # key, its bytes given to the block as they come.
+    raw = lambda do |method, where, data, extra, auth: true, &block|
+      target = URI(where.start_with?("http://", "https://") ? where : root + where)
+      raise Error.new("invalid-argument", "a file's address is reached over HTTPS only") unless target.scheme == "https" || (target.scheme == "http" && %w[127.0.0.1 localhost ::1].include?(target.host))
+
+      request = method == :put ? Net::HTTP::Put.new(target) : Net::HTTP::Get.new(target)
+      request["Authorization"] = "Bearer #{key}" if auth
+      extra.each { |name, value| request[name] = value }
+      request.body = data if data
+      Net::HTTP.start(target.host, target.port, use_ssl: target.scheme == "https", open_timeout: timeout, read_timeout: timeout) do |h|
+        h.request(request) do |response|
+          unless response.is_a?(Net::HTTPSuccess)
+            text = response.read_body.to_s.force_encoding("UTF-8")
+            err = (JSON.parse(text)["error"] rescue nil) || {}
+            raise Error.new(err["code"] || "internal", err["message"] || "HTTP #{response.code}", response.code.to_i)
+          end
+          block ? response.read_body { |chunk| block.call(chunk) } : response.read_body
+        end
+      end
+    end
+    Client.new(call, v1, raw)
+  end
+
+  # A path's segment, as the addresses want it.
+  def self.segment(text) = URI.encode_www_form_component(text.to_s).gsub("+", "%20")
+end
+
+require_relative "ished/grid"

metadata

@@ -0,0 +1,43 @@
+--- !ruby/object:Gem::Specification
+name: ished
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bridge
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/ished.rb
+- lib/ished/grid.rb
+homepage: https://isheddb.com
+licenses:
+- Apache-2.0
+metadata:
+  source_code_uri: https://github.com/treecode9-arch/ished-drivers
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.11
+specification_version: 4
+summary: IshedDB, written as MongoDB’s official driver of each language (Ruby, as
+  the mongo gem)
+test_files: []