Neverending Pun Machine

    TypeScript icon, indicating that this package has built-in type declarations

    0.4.2 • Public • Published

    Mock IPFS Pinning Service

    Implementation of in-memory IPFS Pinning Service API for testing purposes.


    npm i -D mock-ipfs-pinning-service @types/express


    CLI Usage

    You can start the mock server from the command line:

    npx mock-ipfs-pinning-service --port 3000 --token secret

    If token is not passed it will not preform authentification.

    Code Usage

    const { setup } = require('mock-ipfs-pinning-service')
    const port = 3005
    const main = async () => {
       * @type {import('express').Application}
      const service = await setup({ token: 'secret' })
      const server = service.listen(port, () => {
        console.log(`server running on port ${port}`)
      const cleanupEvents = ['beforeExit', 'SIGTERM', 'SIGINT', 'SIGHUP']
      // Express server cleanup handling.
      const cleanup = () => {
        // To prevent duplicated cleanup, remove the process listeners on cleanup
        cleanupEvents.forEach((event) =>, cleanup))
        server.close((err) => {
          if (err) {
          console.log(`server stopped listening on port ${port}`)
      // close the server when your process exits
      cleanupEvents.forEach((event) => process.on(event, cleanup))

    State of the pins is exposed via service.locals.state which you can monkeypatch or replace. Each new request will be served based on that value. All requests perform that perform state updates do them in immutable style and swap the whole value, in other words references are guaranteed to not mutate.

    You can see the status of the server and test individual functions from the SwaggerUI by navigating to http://localhost:${port}/docs/, switching Server to / and then entering access token under Authorize button.

    Log levels


    • --loglevel error to only print errors
    • --loglevel info to print each JSON request and response (default on CLI)
    • --loglevel debug to see low level OpenAPI validation details

    Mocking specific PinStatus response

    By default the mock service will respond with PinStatus.status="queued". This means ipfs pin remote add will hang forever, unless --background is passed, because it will wait for status to change to pinned or failed.

    It is possible to overide this behavior per pin request by prefixing with ${status}-, for example:

    • queued-test0PinStatus.status="queued"pin remote add hangs (needs --background)
    • pinning-test1PinStatus.status="pinning"pin remote add hangs (needs --background)
    • pinned-test2PinStatus.status="pinned"pin remote add responds instantly
    • failed-test3PinStatus.status="failed"pin remote add responds instantly

    Debugging client in go-ipfs (ipfs pin remote)

    One can use this mock service with client included in go-ipfs to debug its behavior:

    // start mock service
    $ npx mock-ipfs-pinning-service --port 5000 --token secret --loglevel info
    // then in other console
    $ ipfs pin remote service add mock "" secret
    $ ipfs pin remote service ls --stat
    mock 0/0/0/1

    The first console will show what happened on the wire:

    Request: GET /pins?limit=1&status=queued headers[host=;user-agent=go-pinning-service-http-client;accept=application/json;authorization=Bearer secret;accept-encoding=gzip] at Fri Apr 23 2021 19:58:49 GMT+0200, IP: ::ffff:, User Agent: go-pinning-service-http-client
    Response Body:
    	"count": 0,
    	"results": []
    Response: 200 3.183 ms  headers[x-powered-by=Express;access-control-allow-origin=*;content-type=application/json; charset=utf-8;content-length=24;etag=W/"18-sS5FLbfK694W6H4gsKxYsIoy1Pk"]


    npm i mock-ipfs-pinning-service

    DownloadsWeekly Downloads





    (Apache-2.0 AND MIT)

    Unpacked Size

    140 kB

    Total Files


    Last publish


    • gozala
    • achingbrain
    • sgtpooki
    • lidel